Copy page

Authentication

Tokens

Authenticated Chief Tools API requests use bearer tokens. Use a team access token for a service owned by one team, a personal access token for your own scripts, or OAuth when your application connects other users' accounts.

Choose a token type

Team access tokens

A team access token always acts for one team. It is the best fit for a server, scheduled job, or shared integration that should keep working for that team without relying on one person's default team.

Create one from the team's settings in Account Chief. Select the team, then find Team API access tokens.

Personal access tokens

A personal access token acts as your user account. Use one for a private script, local development, or a tool that only you operate.

Create one on the API tokens page in Account Chief. A personal token is not fixed to one team. Product APIs that use team-owned resources may use your default team or let you select a team on each request. Follow that product's API introduction for its team-selection rules.

OAuth access tokens

Use OAuth when your application connects accounts belonging to other Chief Tools users. The user signs in to Account Chief and chooses which product permissions to grant. Your application receives a short-lived access token and, when it requests offline_access, a refresh token.

The OAuth and OpenID Connect guide covers client setup, authorization, token exchange, and refresh-token rotation.

Create a personal or team token

1. Give the token a name that identifies the integration and environment.
2. Set an expiration date when the integration has a known end date. Leave it empty only when the token needs to remain valid until you revoke it.
3. Select the narrowest scopes that cover the integration's requests.
4. Create the token and copy its value when Account Chief shows it. You cannot retrieve the value later.
5. Store it in a secret manager or protected environment variable. Do not commit it to source control.

Personal access tokens always include the Account Chief profile, email, and teams scopes. You cannot remove those defaults. Product scopes remain under your control.

Restrict a token to specific resources

Some products let you limit a personal or team token to specific resources, on top of its scopes. In Domain Chief, for example, you can create a token that only works for one or two domains.

When you create the token, select Only selected resources under the product and list the resources one per line. The token can then only reach the listed resources, with the permissions its scopes grant. Each product's scope reference explains which resources you can list and how a restricted token behaves, for example Domain Chief.

You cannot change the resources of an existing token. Create a new token instead, and revoke the old one once you have switched.

Products receive the restriction as RFC 9396 authorization_details, a list of objects with a type such as domainchief:domain and the identifier of an allowed resource.

Send the token

Pass the token in the Authorization header on every API request:

Code
Authorization: Bearer $TOKEN

Do not place a token in a URL or query parameter. URLs commonly appear in browser history, proxy logs, and monitoring tools.

A missing, expired, revoked, or invalid token normally produces 401 Unauthorized. A valid token without the required permission normally produces 403 Forbidden. Check the operation's API reference before adding broader scopes.

Rotate and revoke tokens

Create a replacement before revoking a token that is still in use. Update the integration, verify requests with the new value, then revoke the old token in Account Chief.

Revocation takes effect immediately. Expiration also stops a token without requiring a separate cleanup step.

Recognize Chief Tools tokens

Token prefixes help secret scanners and support tools identify the credential type:

• ctp_ identifies a personal access token.
• ctt_ identifies a team access token.
• cto_ identifies an OAuth access token.
• ctr_ identifies an OAuth refresh token.

Treat the whole value as opaque. Do not infer permissions from its prefix or build authentication logic around its current length.

Chief Tools participates in GitHub secret scanning. When GitHub reports a valid Chief Tools token from a public repository, Chief Tools revokes it. GitGuardian can also detect Chief Tools token patterns, but its alert does not replace revocation and investigation.