> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # API Keys and Management Keys > Create and manage API keys and workspace-scoped management keys in Toqan Router with granular permissions for users and service accounts. See [HTTP URLs and authentication](/docs/reference/base-urls.md) 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](/docs/reference/api-keys/create-a-new-api-key.md). 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 **1. 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**. **2. 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. **3. Set name and project** Enter a **Name** for the key and select the **Project** it will have access to. **4. Set permissions** Choose a permission preset. See [Permissions](#permissions) below. **5. Set expiration (optional)** Set an **Expiration** date if the key should automatically become inactive after a certain date. **6. 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. > [!WARNING] > > The token is only shown once. Store it securely before closing this dialog. It cannot be retrieved afterwards. > [!NOTE] > > To cap a key's **cost**, **token**, or **requests-per-minute** usage, attach a [Budget](/docs/ai-gateway/budgets.md) to it. Budget limits reset on the configured period. See [Rate limits & quotas](/docs/ai-gateway/features/rate-limits.md) 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**. > [!NOTE] > > **Write** permission automatically includes **Read** where Read is available for the endpoint. > [accordion] 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. > [!NOTE] > > 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 > [!NOTE] > > 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](#capabilities). > [!TIP] > > 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 **1. Open the creation panel** In **Settings** → **Organization**, open **Management Keys** and click Key. **2. Enter a name** Enter a **Name** for the key (required, max 128 characters). **3. Set permissions** Select a **Permissions** mode, default is All. See [Permission modes](#permission-modes) below. **4. Set expiration (optional)** Set an **Expiration** date if the key should stop authenticating after a certain date. **5. Create and copy the key** Click Create key. A **Save your key** panel appears showing the token. > [!WARNING] > > 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 | ✓ | ✓ | > [!NOTE] > > 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](/docs/reference/api-keys/create-a-new-api-key.md) and [Management Keys reference](/docs/reference/management-keys/create-a-new-management-key.md) 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: ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} # 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" ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} // 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" }); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} # 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: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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--` 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. > [!WARNING] > > 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](/docs/ai-gateway/budgets.md) 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: ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} # 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": "" } }, "limits": { "period": "BUDGET_PERIOD_MONTHLY", "amount": 100, "token_limit": 1000000 }, "rate_limit": { "requests_per_minute": 60 } }' ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 }, }); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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}, ) ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.