API Token Management

Overview

API tokens allow applications, scripts, and third-party integrations to authenticate with the Ocriva API without using user credentials. Each token carries a set of permissions and scopes that define exactly what it is allowed to do.

Tokens can be scoped to an entire organization or limited to a single project. Only organization owners and admins can create tokens.

Token Types

Prefer project-scoped tokens whenever the integration only needs access to one project. This limits the blast radius if a token is ever compromised.

Creating a Token

Organization-level token:

1. Go to Organization → API Tokens
2. Click New Token
3. Enter a name (max 100 characters) and an optional description (max 500 characters)
4. Select Organization as the token type
5. Choose permissions and scopes (at least one of each is required)
6. Set an expiry date — defaults to 1 year from today if left blank
7. Optionally add an IP whitelist
8. Click Create Token
9. Copy the token value immediately — it is shown only once

Project-level token:

1. Go to Organization → Projects → select a project → API Tokens
2. Follow the same steps, selecting Project as the token type
3. The token is automatically bound to the selected project

Permissions and Scopes

Every token requires at least one permission and at least one scope. These two dimensions work together to control access.

Permissions are free-form string labels you attach to a token to describe its intended access level. Common values are:

Permissions are stored on the token as a plain string array (string[]). There is no fixed enum — you can supply any labels that are meaningful to your integration. Whether a specific permission label is enforced depends on the individual endpoint or guard being accessed; not all endpoints check the permissions field.

Scopes define which resource domains the token is intended to access. Examples include:

Token Format

Tokens are cryptographically random and use the prefix ocr_ followed by 64 hexadecimal characters:

ocr_<64 hex characters>

Example: ocr_a3f1b2c4d5e6...

Using a Token in API Requests

Pass the token in the Authorization header using the Bearer scheme:

GET /api/v1/organizations/{organizationId}/projects HTTP/1.1
Authorization: Bearer ocr_a3f1b2c4d5e6...

The API validates the token on every request, checking that it is active, not expired, and that the request's IP address is on the whitelist (if one is configured). Each successful validation increments the token's usageCount and updates lastUsedAt.

Managing Existing Tokens

Viewing Tokens

Navigate to Organization → API Tokens to see all tokens for the organization. The list shows each token's name, type, scopes, expiry date, active status, and last-used timestamp. The raw token value is never shown after creation.

You can filter by type, active status, project, or search by name or description.

Updating a Token

You can update a token's name, description, permissions, scopes, expiry date, active status, and IP whitelist without rotating the underlying secret.

• Token creators can always update their own tokens
• Organization owners and admins can update any token in the organization

Deactivating a Token

Set isActive to false on a token to immediately block all API requests using that token without deleting it. This is useful for temporarily suspending access while retaining the token configuration.

Regenerating a Token

If a token value is compromised or lost, regenerate it:

1. Open the token from the token list
2. Click Regenerate
3. A new cryptographically random value is generated and returned immediately
4. The old value is invalidated at the same moment
5. Copy and store the new value — it will not be shown again

Deleting a Token

Deleting a token permanently removes it. Use deactivation instead if you might need to re-enable the token later.

• Token creators can delete their own tokens
• Organization owners and admins can delete any token

IP Whitelisting

You can restrict a token to one or more source IP addresses or CIDR ranges:

{
  "ipWhitelist": ["203.0.113.10", "10.0.0.0/8"]
}

Requests from IPs not on the whitelist are rejected even if the token itself is valid. Leave ipWhitelist empty (or omit it) to allow requests from any IP.

Token Expiry

Tokens have a mandatory expiry date. The default is 1 year from creation if you do not specify a date. After the expiry date:

• The token is rejected on all API requests
• The isActive field remains unchanged — the token is expired by date, not deactivated
• You must regenerate or create a new token to restore access

Set up calendar reminders or monitoring alerts before critical tokens expire to avoid unexpected service interruptions.

Security Best Practices

• Use project-scoped tokens over organization-scoped tokens when the integration only requires access to one project.
• Grant the minimum permissions and scopes needed. A read-only analytics integration should use read + analytics, not write + all scopes.
• Store tokens in a secrets manager. Never hard-code tokens in source code, configuration files, or commit them to version control.
• Rotate tokens regularly. Even without a suspected compromise, periodic rotation reduces the window of exposure.
• Use IP whitelisting for server-to-server integrations. If your integration runs from a fixed IP or subnet, whitelist it to prevent token misuse from other locations.
• Deactivate instead of deleting when suspending a token temporarily. This preserves usage history and makes re-enabling straightforward.
• Monitor lastUsedAt and usageCount. Unexpected spikes or timestamps outside expected usage windows can indicate a compromised token.
• Set short expiry dates for tokens used in automated scripts. A 30- or 90-day expiry forces regular rotation and limits long-term exposure.