API Keys and Management Keys

See HTTP URLs and authentication and the API reference for complete request and response formats.

API Keys

What are API Keys

API Keys are tokens that authenticate requests to Toqan Router. A key covers one project, or every project in the workspace when created without one through the API. Its permissions limit what it can do. Two key types are available, chosen by the key’s owner.

User keys

Tied to a specific user account. Automatically revoked if the user is removed from the organization or the project one of their keys is bound to. Use user keys for personal use and local development.

Service account keys

Not tied to any individual user, with a lifecycle independent of user membership. Only workspace admins can create service account keys. Use service account keys for production systems, so access does not break when a team member leaves.

Viewing API Keys

Navigate to Settings > API Keys to see all keys across projects. The table shows the following columns:

Column	Description
Created	Date the key was created
Name	Key label
Project	The project the key can reach
Type	`User` or `Service`
Status	`Active`, `Disabled`, or `Revoked`
Permissions	`All`, `Read only`, or `Restricted`
Expiration	When the key stops authenticating, or `No expiration`
Created by	User who created the key

Use the menu to filter by Type or Permissions.

Creating an API Key

Open the creation panel

Navigate to Settings > API Keys and select Secret key. The Create new secret key sheet opens with Owned by, Name, Project, Permissions, and Expiration.

Choose an owner

Under Owned by, select You to create a User key, or Service account to create a key not tied to any individual user.

Set name and project

Enter a Name for the key and select the Project it will have access to.

Set permissions

Choose a permission preset. See Permissions below.

Set expiration (optional)

Set an Expiration date if the key should automatically become inactive after a certain date.

Create and copy the key

Select Create secret key. A Save your key dialog appears showing the token and its permissions summary.Click Copy to copy the token.

The token is only shown once. Store it securely before closing this dialog. It cannot be retrieved afterwards.

To cap a key’s cost, token, or requests-per-minute usage, attach a Budget to it. Budget limits reset on the configured period. See Rate limits & quotas for what the gateway enforces at each layer.

Permissions

Preset	Description
All	Read and write access to all API resources
Read only	Read access to all API resources
Restricted	Custom per-resource access

With Restricted, set the permission for each resource individually: None, Read, or Write.

Write permission automatically includes Read where Read is available for the endpoint.

Restricted permission resources

Resource	None	Read	Write
Agent schedules	✓	✓	✓
Agents	✓	✓	✓
Annotations	✓	✓	✓
Chunking	✓	✓	✓
Datasets	✓	✓	✓
Deployments	✓	✓	✓
Evaluators	✓	✓	✓
External agents	✓	✓	✓
Feedback	✓	✓	✓
Files	✓	✓	✓
Guardrail rules	✓	✓	✓
Human evaluations	✓	✓	✓
Identities	✓	✓	✓
Knowledge bases	✓	✓	✓
Memory stores	✓	✓	✓
Policies	✓	✓	✓
Projects	✓	✓	✓
Prompts	✓	✓	✓
Reporting	✓	✓
Routing rules	✓	✓	✓
SCIM	✓	✓	✓
Skills	✓	✓	✓
Tools	✓	✓	✓
Gateway
Batches	✓		✓
Chat completions	✓		✓
Classify	✓		✓
Embeddings	✓		✓
Images	✓		✓
Models	✓	✓
Moderations	✓		✓
OCR	✓		✓
Rerank	✓		✓
Responses	✓	✓	✓
Speech	✓		✓
Transcriptions	✓		✓

Managing Keys

Select the menu on any key to access the following actions:

Edit: update the name, permissions, or expiration date. The owner type cannot be changed after creation.
Duplicate: opens the creation panel pre-filled with the key’s current settings.
Delete: permanently removes the key. This cannot be undone.

A Revoked status means the key belonged to a user who was removed from the organization or project, or it has been revoked manually. Revocation is permanent.

Management Keys

Overview

Management Keys are only available to workspace admins. The Management Keys page is not visible to non-admin members.

Management Keys are workspace-scoped tokens for authenticating workspace administration operations. Each key grants read or write access to every capability in Capabilities.

Management Keys cannot be used to query models or agents. Use a standard API Key for inference and product endpoints.

Use cases

Automating workspace provisioning via the API.
Delegating API key rotation to a deployment pipeline without granting full admin access.
Letting a billing automation script read and update Budgets without exposing API key management.

Workspace administration endpoints

API keys cannot administer API keys or Budgets, so those two families need a Management Key. Project and Smart Router management follows the key’s scope: an all-projects key can create, update, and delete them, a single-project key cannot.

Endpoint family	Access
`/v2/api-keys*`	List, retrieve, create, update, and delete API keys. `/v2/api-keys/capabilities` is public.
`/v2/budgets*`	List, retrieve, create, update, reset, and delete Budgets.
`/v2/projects*`	An all-projects API key manages Projects across the workspace; a single-project key can only list or retrieve its own Project.
`/v2/smart-routers*`	An all-projects API key lists, creates, updates, enables, disables, and deletes Smart Routers across the workspace.

View Management Keys

Open Management Keys in the Settings sidebar, under Organization, to view all keys in the workspace. Click any row to open the edit panel and update the key’s name, permissions, or expiration date. Hover a row and click for additional options:

Edit: open the edit panel to update the key’s name, permissions, or expiration date.
Duplicate: create a new key with the same permissions.
Delete: permanently remove the key from the workspace.

Create a Management Key

Open the creation panel

In Settings → Organization, open Management Keys and click Key.

Enter a name

Enter a Name for the key (required, max 128 characters).

Set permissions

Select a Permissions mode, default is All. See Permission modes below.

Set expiration (optional)

Set an Expiration date if the key should stop authenticating after a certain date.

Create and copy the key

Click Create key. A Save your key panel appears showing the token.

The token is only shown once. Store it securely before closing this panel. It cannot be retrieved afterwards.

Permission modes

Mode	Description
All	Full read and write access to all capabilities.
Restricted	Configure access per capability. Each capability can be set to None, Read, or Write independently.
Read only	Read access to all capabilities.

Capabilities

The Restricted mode shows one row per capability. None grants no access to that capability, Read lists and views its resources, and Write also creates, updates, and deletes them. A ✗ marks a level the picker omits for that capability, which then takes only None or Read.

Capability	Read	Write
API keys	✓	✓
Audit logs	✓	✗
Budgets	✓	✓
Environments	✓	✓
Evaluators	✓	✓
Guardrail rules	✓	✓
Hub	✓	✗
Logs	✓	✗
Management keys	✓	✓
MCP gateways	✓	✓
MCP servers	✓	✓
Model fusions	✓	✓
Models	✓	✓
Notifiers	✓	✓
Policies	✓	✓
Projects	✓	✓
Reporting	✓	✗
Routing rules	✓	✓
Secrets	✓	✓
Smart routers	✓	✓
Teams	✓	✓
Traces	✓	✗
Users	✓	✓
Vaults	✓	✓
Workspace	✓	✓
Workspace models	✓	✓

Management Keys are not available through MCP. Use the REST API to manage keys programmatically.

Manage keys programmatically

Create, update, revoke, and delete API Keys and Management Keys with the API instead of the console. The full endpoint reference is on the API Keys reference and Management Keys reference pages.

Authenticating with a Management Key

Key management requests authenticate with a Management Key, never an API key. API Keys are inference credentials scoped to project resources and cannot administer keys.

Pass a Management Key as the bearer token, or as the SDK API key.
A Management Key with the api-key write grant can list, create, update, revoke, and delete API Keys.

The SDK exposes these operations as api_keys / apiKeys and management_keys / managementKeys: API Keys SDK, Management Keys SDK.

Key lifecycle in code

These examples use a Management Key as TOQAN_API_KEY.

Operation	Endpoint	Notes
Create	`POST /v2/api-keys`	`name` is required; scope, permissions, and expiration are optional. An omitted `permission_mode` defaults to `all`, which grants read and write access to every capability
Disable	`PATCH /v2/api-keys/{api_key_id}`	Set `status` to `disabled`; reversible
Revoke	`PATCH /v2/api-keys/{api_key_id}`	Set `status` to `revoked`; permanent
Delete	`DELETE /v2/api-keys/{api_key_id}`	Permanently removes the key
List	`GET /v2/api-keys`	Paginated; never returns the secret
Retrieve	`GET /v2/api-keys/{api_key_id}`	Never returns the secret

Create a project-scoped key with restricted permissions:

curl -X POST https://router.toqan.ai/eu/v2/api-keys \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support automation key",
    "project_scope": {
      "mode": "single",
      "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V"
    },
    "permission_mode": "restricted",
    "access": {
      "agent": "write",
      "deployment": "read"
    }
  }'

Disable, revoke, or delete an existing key:

# Disable (reversible)
curl -X PATCH https://router.toqan.ai/eu/v2/api-keys/01HZXW2K7Y8Q9M0N1P2R3S4T5V \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "disabled"}'

# Revoke (permanent)
curl -X PATCH https://router.toqan.ai/eu/v2/api-keys/01HZXW2K7Y8Q9M0N1P2R3S4T5V \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "revoked"}'

# Delete
curl -X DELETE https://router.toqan.ai/eu/v2/api-keys/01HZXW2K7Y8Q9M0N1P2R3S4T5V \
  -H "Authorization: Bearer $TOQAN_API_KEY"

// Disable (reversible)
await client.apiKeys.update({
  apiKeyId: "01HZXW2K7Y8Q9M0N1P2R3S4T5V",
  updateApiKeyRequest: { status: "disabled" },
});

// Revoke (permanent)
await client.apiKeys.update({
  apiKeyId: "01HZXW2K7Y8Q9M0N1P2R3S4T5V",
  updateApiKeyRequest: { status: "revoked" },
});

// Delete
await client.apiKeys.delete({ apiKeyId: "01HZXW2K7Y8Q9M0N1P2R3S4T5V" });

# Disable (reversible)
client.api_keys.update(
    api_key_id="01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    status="disabled",
)

# Revoke (permanent)
client.api_keys.update(
    api_key_id="01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    status="revoked",
)

# Delete
client.api_keys.delete(api_key_id="01HZXW2K7Y8Q9M0N1P2R3S4T5V")

To rotate a key, create a replacement key with the same configuration, then revoke the old one. Rotation is create followed by revoke; there is no dedicated rotate endpoint.

Project scope

project_scope decides which projects the key reaches. On create, omit it and the key reaches every project in the workspace.

`mode`	`project_id`	Effect
`all`	Omitted	The key reaches every project in the workspace.
`single`	Required	The key reaches only that project.

mode takes the short values all and single, or the enum values PROJECT_SCOPE_MODE_ALL and PROJECT_SCOPE_MODE_SINGLE. The nested spelling reaches the same scopes: {"all": {}} or {"single": {"project_id": "..."}}. Send one spelling per request. projects is the legacy single-element array that older clients send instead of project_scope. It sets a single-project scope, and when a request carries both fields they must name the same project.

Permission model

permission_mode selects the preset:

Mode	Description
`all`	Read and write access to all domains in the API key capability catalog
`read_only`	Read access to all domains in the API key capability catalog
`restricted`	Per-domain access via the `access` map

With restricted, the access map assigns a level to each domain. Write includes read:

Level	Access
`none`	No access
`read`	Read access
`write`	Read and write access

The capability catalog lists the domains a key can be granted: GET /v2/api-keys/capabilities returns each domain with its id, display name, group, and read / write availability. Use the catalog to discover grantable domains at runtime instead of hard-coding the list. The access keys are the id values the catalog returns (responses, model), not the display_name values (Responses, Models). For example, a restricted key that may run Responses and read the model catalog in every project:

{
  "name": "Support automation key",
  "permission_mode": "restricted",
  "access": {
    "responses": "write",
    "model": "read"
  }
}

The secret is returned once

The create response returns the raw token exactly once, in the sk-orq-<id>-<secret> format. Store it immediately: the API stores only a displayable token_prefix and a hash of the secret, so list and retrieve responses never include the token.

The token is only returned in the create response. Store it securely and treat it like a password; it cannot be retrieved afterwards.

For how every other kind of secret is stored, read, and rotated, see Secrets management.

Cost, token, and rate limits

Keys do not carry limit fields. Attach cost, token, and requests-per-minute limits with a Budget scoped to the key. Budgets are workspace resources and require a Management Key; regular API Keys cannot manage them.

Example: provision a per-customer key with a spend cap

Create a key scoped to the customer’s project, then attach a monthly spend cap as a Budget scoped to that key:

# Create the customer key; capture the key id and token from the response
curl -X POST https://router.toqan.ai/eu/v2/api-keys \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Acme key",
    "project_scope": {
      "mode": "single",
      "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V"
    },
    "permission_mode": "restricted",
    "access": {
      "agent": "write"
    }
  }'

# Cap cost, tokens, and rate with a Budget scoped to the key
curl -X POST https://router.toqan.ai/eu/v2/budgets \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": { "api_key": { "api_key_id": "<key id from create>" } },
    "limits": {
      "period": "BUDGET_PERIOD_MONTHLY",
      "amount": 100,
      "token_limit": 1000000
    },
    "rate_limit": { "requests_per_minute": 60 }
  }'

const key = await client.apiKeys.create({
  name: "Customer Acme key",
  projectScope: {
    mode: "single",
    projectId: "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
  },
  permissionMode: "restricted",
  access: {
    agent: "write",
  },
});

console.log(key.token);

await client.budgets.create({
  scope: { apiKey: { apiKeyId: key.id } },
  limits: {
    period: "BUDGET_PERIOD_MONTHLY",
    amount: 100,
    tokenLimit: 1000000,
  },
  rateLimit: { requestsPerMinute: 60 },
});

key = client.api_keys.create(
    name="Customer Acme key",
    project_scope={
        "mode": "single",
        "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    },
    permission_mode="restricted",
    access={
        "agent": "write",
    },
)

print(key.token)

client.budgets.create(
    scope={"api_key": {"api_key_id": key.id}},
    limits={
        "period": "BUDGET_PERIOD_MONTHLY",
        "amount": 100,
        "token_limit": 1000000,
    },
    rate_limit={"requests_per_minute": 60},
)

Toqan Router

Overview

APIs

MCP Portal

Routing

Security & Privacy

Model Capabilities

Server Tools

Common Scenarios

Provider setup

API Keys

What are API Keys

User keys

Service account keys

Viewing API Keys

Creating an API Key

Permissions

Managing Keys

Management Keys

Overview

Use cases

Workspace administration endpoints

View Management Keys

Create a Management Key

Permission modes

Capabilities

Manage keys programmatically

Authenticating with a Management Key

Key lifecycle in code

Project scope

Permission model

The secret is returned once

Cost, token, and rate limits

Example: provision a per-customer key with a spend cap

​API Keys

​What are API Keys

​User keys

​Service account keys

​Viewing API Keys

​Creating an API Key

​Permissions

​Managing Keys

​Management Keys

​Overview

​Use cases

​Workspace administration endpoints

​View Management Keys

​Create a Management Key

​Permission modes

​Capabilities

​Manage keys programmatically

​Authenticating with a Management Key

​Key lifecycle in code

​Project scope

​Permission model

​The secret is returned once

​Cost, token, and rate limits

​Example: provision a per-customer key with a spend cap

API Keys

What are API Keys

User keys

Service account keys

Viewing API Keys

Creating an API Key

Permissions

Managing Keys

Management Keys

Overview

Use cases

Workspace administration endpoints

View Management Keys

Create a Management Key

Permission modes

Capabilities

Manage keys programmatically

Authenticating with a Management Key

Key lifecycle in code

Project scope

Permission model

The secret is returned once

Cost, token, and rate limits

Example: provision a per-customer key with a spend cap