Create an API token

Scripts and CI call the NebulaCtrl API with an API token instead of a browser session. A token belongs to one organization and acts with the role you give it.

Before you beginCopy Anchor Link

• You need the admin or owner role and a signed-in browser session. A token cannot create another token.
• Know what the integration does. The role you pick decides which API operations the token can call; the role table lists what each role can do.

Create a tokenCopy Anchor Link

1. Open Settings > API tokens and select Create token.
2. Enter a Name that tells you what uses the token, for example ci-deploy.
3. Choose a Role: Viewer, Deployer (the default) or Admin. A token cannot have the owner role, and you cannot give it a role above your own.
4. Under Projects, keep All projects (includes projects created later) or choose Only some and tick the projects.
5. Choose when it Expires: 30 days, 90 days (the default), 1 year or never.
6. Select Create token.
7. Copy the token from Copy your token now and store it. It is shown once. The dialog closes only with Done.

The token has the form nbl_ID_SECRET. NebulaCtrl stores a SHA-256 hash of the secret, so it cannot show the token again.

Call the API with the tokenCopy Anchor Link

Send the token as a bearer credential. A token already belongs to one organization, so the X-Nebula-Organization header is optional; if you send it, it must name that organization.

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $NEBULA_TOKEN" \
  https://nebula.example.com/api/v1/projects

NEBULA_TOKEN holds the token, and https://nebula.example.com is your control plane's public URL.

200

The HTTP API reference lists every operation and the errors it returns. A token that is revoked, expired or malformed gets no identity at all, so the operation answers sign in or provide an API token to ACTION.

Limit a token to projectsCopy Anchor Link

A project-limited token reaches only its projects, with the role you gave it. List operations, streams and the Activity page show only those projects.

It is refused everything that acts on the whole organization, even reading it: clusters, nodes, members, teams, policy, API tokens, Git connections and registry credentials. It cannot create projects, clusters or servers. The refusal reads this API token is limited to specific projects and cannot perform ACTION, which acts on the whole organization; use a token without project limits or sign in.

If every project a token is limited to is deleted, the token stays limited and reaches nothing.

What no token can doCopy Anchor Link

Whatever its role, a token cannot:

• create API tokens;
• create organizations, send or accept invitations, or read your notification inbox;
• finish a GitHub App connection, which runs in the browser;
• delete or transfer an organization, or grant or remove the owner role;
• request or cancel a control plane update, which needs an owner of the Default organization;
• turn on Require two-factor for everyone. Tokens are also exempt from that requirement.

In production approvals, a token acts in the name of the person who created it, and only while the token is active.

Rotate and revokeCopy Anchor Link

A token cannot be edited, and there is no rotate action. To rotate:

1. Create a new token with the same role and scope.
2. Switch your integration to it.
3. Select Revoke on the old token's row, then Revoke token.

Revoking takes effect on the token's next request. Open event streams re-check their credential every 30 seconds and close once it is revoked. Any admin or owner can revoke any token in the organization.

NebulaCtrl revokes every token a person created when that person is removed, leaves, has their role lowered, or transfers ownership.

VerifyCopy Anchor Link

• The table in Settings > API tokens lists the token with its Role, Projects and Expires columns.
• Last used changes from never after the first call. It updates at most once a minute.
• Creating and revoking a token are audit events, and each action the token takes is recorded with the token as the actor. See the audit log.

Tokens with no expiry, or with fewer than 14 days left, appear in a warning color in the table.

Next stepsCopy Anchor Link