Manage API tokens
A personal API token lets a script, a CI job, or an MCP client call Orchard without a browser. The token acts as your account, so it can never do more than you can, and you can limit it further with an access level, a lifetime, and a list of projects.
Token access levels
Section titled “Token access levels”Each token has one access level. Each level includes the level before it.
| Level | Allows |
|---|---|
read | Most read requests. Some reads that return secrets require deploy. |
deploy | read, plus requests that create, update, delete, scale, or restart. |
exec | deploy, plus shells in pods and databases, commands inside containers, and creating or editing sandboxes. |
At any access level, a token cannot register a passkey, set a password, or call instance setup and admin routes.
Tokens cannot manage an organization’s SSO or SCIM, or change passkeys. A token restricted to projects also cannot use account routes, such as sessions, tokens, GitHub, or invitations, apart from reading its own user.
Tokens and single sign-on
Section titled “Tokens and single sign-on”An organization that requires single sign-on only accepts tokens created after signing in through its provider. Such a token works in that organization and nowhere else, and its row in the list says so. It also cannot create more tokens.
A token created any other way gets a 403 with the error org_sso_required in that organization, and keeps working in your other organizations. To fix this, sign in through the organization’s provider and create a new token at Account settings > API tokens.
Owners of the organization are exempt.
Create a token
Section titled “Create a token”- Go to Account settings > API tokens.
- Select New token.
- In Name, enter a name that describes where you use the token.
- In Access, select Read, Deploy, or Exec.
- Select Create token.
- Copy the token. Orchard does not show it again.
- Select Done.
Run the following command:
orchard auth token create --name ci --scope deployThe command prints the token once. Copy it before you close the terminal.
| Flag | Description |
|---|---|
--name | Token name. Required. |
--scope | read, deploy, or exec. The default is read. |
--expires-in | Lifetime, such as 30d or 12h. The default and maximum are 90d. |
--project | Restrict the token to a project ID or slug. You can repeat this flag. |
A token expires after 90 days unless you set a shorter lifetime. The dashboard always uses 90 days. To set a shorter lifetime or restrict a token to specific projects, use the CLI.
Use a token
Section titled “Use a token”Send the token in the Authorization header:
curl "https://orchard.example.com/apiv1/auth/me" \ --header "Authorization: Bearer <API_TOKEN>"To use a token with the CLI, set the ORCHARD_API_URL and ORCHARD_API_TOKEN environment variables:
export ORCHARD_API_URL=https://orchard.example.comexport ORCHARD_API_TOKEN=<API_TOKEN>To use a token with an MCP client, refer to Connect an MCP client.
Rename a token
Section titled “Rename a token”- Go to Account settings > API tokens.
- On the token row, select Rename.
- Enter the new name.
- Save the name.
Revoke a token
Section titled “Revoke a token”Requests that use a revoked token fail immediately.
- Go to Account settings > API tokens.
- On the token row, select Revoke.
- Select Revoke token.
-
List your tokens to find the token ID:
orchard auth token list -
Revoke the token:
orchard auth token revoke <TOKEN_ID>
Rotate a token
Section titled “Rotate a token”- Create a new token.
- Update the script, job, or client to use the new token.
- Revoke the old token.
Related resources
Section titled “Related resources”- Update an app with a webhook - Redeploy an app from CI with a deploy webhook token instead of a personal token.
- Set up SCIM provisioning - Sync people from your identity provider with an organization token.
orchard authreference - Every flag of the sign-in, session, and token commands.