API authentication

Send only access tokens to the APICopy Anchor Link

Every protected API accepts only an access token in the Authorization: Bearer <token> header. Access tokens last five minutes, and ntro token gives you one.

export NITROSHIP_ACCESS_TOKEN="$(ntro token)"
curl --fail-with-body \
  -H "Authorization: Bearer $NITROSHIP_ACCESS_TOKEN" \
  https://api.nitroship.co/v1/me

ntro token prints an access token for the account you're logged in with. Where you can't log in, such as CI or scripts, put an ntro_ API token in NITROSHIP_TOKEN first; the CLI uses it to get an access token and prints that.

export NITROSHIP_TOKEN='ntro_...'
export NITROSHIP_ACCESS_TOKEN="$(ntro token)"

Only the token is written to standard output, so you can capture it in a variable as shown. Add --json to get {"accessToken": "..."} instead.

Requests are allowed only within the user's team roles, and before the email is verified, change requests may be rejected with 403 email_verification_required.

Recommended pattern for automationCopy Anchor Link

1. Reuse an access token for its five minutes. Don't fetch a new one for every request.
2. If the API returns 401, run ntro token again and retry that request once.
3. If the retry also returns 401, stop and treat it as an error. The API token may have been revoked or expired.

If you only use CLI commands such as ntro deploy, you don't need any of this; the CLI gets access tokens on its own.

Good to knowCopy Anchor Link

• Revocation timing: once you revoke an API token, it can't be used to get new access tokens. An access token already issued stays usable until its five minutes are up.
• Last used: each time an API token is used to get an access token, its last-used time is updated.
• No token management: an access token obtained with an API token cannot create, list, or revoke API tokens. Managing tokens requires an access token from logging in. See API tokens.
• Secrets: inject tokens from a secret store and never print or log them.