Skip to content
Install

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.

Each token has one access level. Each level includes the level before it.

LevelAllows
readMost read requests. Some reads that return secrets require deploy.
deployread, plus requests that create, update, delete, scale, or restart.
execdeploy, 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.

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.

  1. Go to Account settings > API tokens.
  2. Select New token.
  3. In Name, enter a name that describes where you use the token.
  4. In Access, select Read, Deploy, or Exec.
  5. Select Create token.
  6. Copy the token. Orchard does not show it again.
  7. Select Done.

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.

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.com
export ORCHARD_API_TOKEN=<API_TOKEN>

To use a token with an MCP client, refer to Connect an MCP client.

  1. Go to Account settings > API tokens.
  2. On the token row, select Rename.
  3. Enter the new name.
  4. Save the name.

Requests that use a revoked token fail immediately.

  1. Go to Account settings > API tokens.
  2. On the token row, select Revoke.
  3. Select Revoke token.
  1. Create a new token.
  2. Update the script, job, or client to use the new token.
  3. Revoke the old token.