API Tokens & Personal Access Tokens

Anything that talks to Openlane without a browser (CI pipelines, scripts, integrations, the CLI) authenticates with a token. Openlane has two kinds, and picking the right one is mostly a question of who the action should be attributed to.

Which Token Should I Use?

	Organization API Token	Personal Access Token (PAT)
Prefix	tola_	tolp_
Acts as	The organization, with explicitly granted scopes	You, with your existing permissions
Managed by	Organization administrators	The individual user
Best for	CI/CD, system integrations, shared automation	Personal scripts, local development, CLI use

The rule of thumb: if the automation should keep working after you leave the company, use an organization API token. If it's your personal tooling and its actions should show up in the audit trail as you, use a PAT.

Scopes

Organization API tokens are scoped per object type in object:action format, for example evidence:read, evidence:write, or control:delete. Most object types support read, write, and delete actions independently, so grant each token only the specific actions it needs. Avoid broad grants for production tokens: a token that uploads evidence doesn't need control:delete.

PATs don't need explicit scoping for most uses; they inherit the permissions of the user who created them, including group memberships.

Creating and Managing Tokens

Create tokens in the console under developer settings, or via the API:

mutation CreateAPIToken($input: CreateAPITokenInput!) {
  createAPIToken(input: $input) {
    apiToken {
      id
      name
      token
      scopes
      expiresAt
    }
  }
}

mutation CreatePersonalAccessToken($input: CreatePersonalAccessTokenInput!) {
  createPersonalAccessToken(input: $input) {
    personalAccessToken {
      id
      name
      token
      expiresAt
    }
  }
}

The token value is returned once, at creation. Store it in your secrets manager immediately; you can't retrieve it again.

Revoke a token by setting it inactive (or deleting it outright with deleteAPIToken):

mutation RevokeAPIToken($id: ID!) {
  updateAPIToken(id: $id, input: { isActive: false }) {
    apiToken {
      id
      isActive
    }
  }
}

The same pattern works for PATs via updatePersonalAccessToken. For the complete field reference, see the GraphQL object reference.

Using a Token

Pass the token as a bearer token in the Authorization header:

# GitHub Actions example
env:
  OPENLANE_API_TOKEN: ${{ secrets.OPENLANE_API_TOKEN }}

steps:
  - name: Upload compliance evidence
    run: |
      curl -X POST "https://api.theopenlane.io/query" \
        -H "Authorization: Bearer $OPENLANE_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"query": "mutation { createEvidence(input: {...}) { evidence { id } } }"}'

Security Practices

• Set expiration dates. Every token should have one; expiry bounds the exposure window of a forgotten token, and a pipeline broken by an expired token is recoverable.
• Rotate on a schedule and immediately when someone with access to the token leaves.
• Grant least privilege. Scope organization tokens to the specific object:action pairs the job needs.
• Never log token values. Store them in a secrets manager; treat any exposed token as compromised and revoke it.
• Review active tokens periodically. Token usage is logged, and lastUsedAt makes stale tokens easy to spot.

Every token operation and use is recorded for audit purposes, so token activity can serve as evidence of controlled programmatic access.

Troubleshooting

• 401 / authentication failed: check the prefix; organization tokens start with tola_, PATs with tolp_. Make sure the full value was copied and the token hasn't expired or been revoked.
• 403 / permission denied: for organization tokens, the scope grant is missing the object:action you're attempting; for PATs, the owning user lacks the permission.
• Works locally, fails in CI: usually a secrets configuration issue; echo the token length (never the value) to confirm it's set.

FAQ

What happens to a PAT when the user is deactivated?

Its access goes with them; PATs act as their owner. This is exactly why shared automation belongs on organization API tokens.

Can I see a token's value again after creation?

No. The value is shown once. If it's lost, revoke the token and create a new one.

Where do I see what a token has been doing?

Token operations generate audit events, and each token records its last-used timestamp; start there when reviewing or investigating token activity.