API tokens
Create ntro_ tokens for CI and scripts, use them safely, and revoke them.
An API token is a long-lived key for CI and scripts, where nobody can log in through a browser. It starts with ntro_ and acts with the permissions of the user who created it.
Create a token
On the API tokens page in the console, press Create token. Choose a name and an expiry (never, or 1 to 365 days).
The token string is shown only once, at creation
Once you close the dialog you cannot see it again. Put it straight into your CI's secret store (GitHub Actions secrets, for example). If you lose it, revoke it and create a new one.
Use it in CI
Pass the token in the NITROSHIP_TOKEN environment variable and the CLI picks it up.
export NITROSHIP_TOKEN='ntro_...'
ntro whoami
ntro deploy ./dist --app my-app --prod- run: ntro deploy . --app my-app --prod
env:
NITROSHIP_TOKEN: ${{ secrets.NITROSHIP_TOKEN }}You can also pass --token ntro_..., but command-line arguments can show up in process listings and shell history. In automation, inject the environment variable from a secret store.
- A token only works within its creator's team roles. For example, it cannot deploy to a team where the creator is a
viewer. - Changes such as creating apps and deploying require an account with a verified email.
Revoke a token
Delete tokens you no longer need, or suspect have leaked, from the API tokens list in the console right away. A deleted token can no longer be used, although, as explained below, an access token already issued from it can keep working for up to five minutes.
How it works (reference)
API tokens are never sent to the API directly. The CLI first uses the API token to get a five-minute access token, then sends only that access token with API requests.
- The access token is reused until it expires. If the API returns
401, the CLI gets a new one and retries that request once. - Each time an access token is issued, Nitroship checks whether the API token has expired or been revoked and whether the user is suspended, and records when it was last used.
- A revoked API token can't get new access tokens, but an access token already issued stays usable until its five minutes are up.
To call the REST API without the CLI, get an access token with ntro token. API authentication shows how.
Manage tokens through the API
You can also manage tokens through the API instead of the console. This requires an access token obtained by logging in; an API token, or an access token swapped from one, cannot create, list, or revoke API tokens.
| Request | What it does |
|---|---|
POST /v1/identity/tokens | Create a token. Body {"name": "...", "expiresInDays": 30} (expiresInDays is optional, 1–365) |
GET /v1/identity/tokens | List tokens. Only details such as name and expiry; no token strings. |
DELETE /v1/identity/tokens/{tokenId} | Revoke a token |