API Keys and Management Keys

API Keys

What are API Keys

API Keys are secure tokens used to authenticate requests to Orq.ai. Each key is scoped to a single project and carries a set of permissions that control what it can do. Two key types are available, chosen by the key’s owner.

User keys

Tied to a specific user account and project. Automatically revoked if the user is removed from the organization or project. 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 > Organization > 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
Type	`User` or `Service`
Status	`Active`, `Disabled`, or `Revoked`
Permissions	`All`, `Read only`, or `Restricted`
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 > Organization > API Keys and select Create API key.

Create API key panel showing fields for owner, name, project, permissions, and expiration. — The API key creation panel.

Choose an owner

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 API key. A Save your key dialog appears showing the token and its permissions summary.

Save your key dialog showing the API key token with a Copy button and a Permissions summary reading Read and write API resources. — The Save your key dialog appears once after creation.

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	✓	✓	✓
Feedback	✓	✓	✓
Files	✓	✓	✓
Guardrail rules	✓	✓	✓
Human evaluations	✓	✓	✓
Identities	✓	✓	✓
Knowledge bases	✓	✓	✓
Memory stores	✓	✓	✓
Policies	✓	✓	✓
Projects	✓	✓	✓
Prompts	✓	✓	✓
Reporting	✓	✓
Routing rules	✓	✓	✓
Skills	✓	✓	✓
Tools	✓	✓	✓
Gateway
Chat completions	✓		✓
Embeddings	✓		✓
Images	✓		✓
Models	✓	✓
Moderations	✓		✓
OCR	✓		✓
Rerank	✓		✓
Responses	✓	✓	✓
Speech	✓		✓
Transcriptions	✓		✓

Managing Keys

API Keys management table listing keys with columns for name, type, status, permissions, and created by. — The API Keys management table showing all keys, their type, status, permissions, and actions.

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. They can manage API keys, Budgets, Projects, and Smart Routers.

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

Standard API keys are project-scoped. Use a Management Key for these workspace administration endpoints:

Endpoint family	Management Key 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/budgets/check` accepts a project-scoped API key.
`/v2/projects*`	Manage Projects across the workspace. A project-scoped API key can only list or retrieve its selected Project.
`/v2/smart-routers*`	List, retrieve, create, update, enable, disable, and delete Smart Routers.

Notifiers are intentionally not listed here: their routes are project-scoped and do not require a Management Key. Project-scoped API keys can access the Notifiers API for their selected project.

View Management Keys

Navigate to Settings → Organization → Management Keys to view all keys in the workspace.

Management Keys list with columns for Created date, Name, Status, Permissions, and Created by. — The Management Keys list showing key name, status, permission mode, and creator.

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

Navigate to Settings → Organization → Management Keys and click New key.

Create new key dialog showing Name field, Permissions toggle with All, Restricted, and Read only options, API keys and Budgets capability rows, and an Expiration date field. — The Create new key dialog with fields for name, permissions, per-capability access, and expiration date.

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

Capability	None	Read	Write
API keys	No access.	List and view workspace API keys.	List, view, create, update, and revoke workspace API keys.
Budgets	No access.	List and view workspace Budgets.	List, view, create, and update workspace Budgets.
Projects	No access.	List and view workspace Projects.	List, view, create, update, and delete workspace Projects.
Smart Routers	No access.	List and view workspace Smart Routers.	List, view, create, update, enable, disable, and delete workspace Smart Routers.

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 project-scoped inference credentials 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.
Managing Management Keys requires the management-key grant, which is not part of the All or Read only presets. Grant it explicitly to a Management Key that must administer other Management 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 ORQ_API_KEY.

Operation	Endpoint	Notes
Create	`POST /v2/api-keys`	`name` is required; scope, permissions, and expiration are optional
Disable	`PATCH /v2/api-keys/{api_key_id}`	Set `status` to `API_KEY_STATUS_DISABLED`; reversible
Revoke	`PATCH /v2/api-keys/{api_key_id}`	Set `status` to `API_KEY_STATUS_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://my.orq.ai/v2/api-keys \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support automation key",
    "project_scope": {
      "single": { "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V" }
    },
    "permission_mode": "PERMISSION_MODE_RESTRICTED",
    "access": {
      "agent": "ACCESS_LEVEL_WRITE",
      "deployment": "ACCESS_LEVEL_READ"
    }
  }'

import { Orq } from "@orq-ai/node";

const client = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const result = await client.apiKeys.create({
  name: "Support automation key",
  projectScope: {
    single: { projectId: "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V" },
  },
  permissionMode: "PERMISSION_MODE_RESTRICTED",
  access: {
    agent: 3,
    deployment: 2,
  },
});

console.log(result.id);
console.log(result.token);

import os
from orq_ai_sdk import Orq

client = Orq(api_key=os.environ["ORQ_API_KEY"])

result = client.api_keys.create(
    name="Support automation key",
    project_scope={
        "single": {"project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V"},
    },
    permission_mode="PERMISSION_MODE_RESTRICTED",
    access={
        "agent": 3,
        "deployment": 2,
    },
)

print(result.id)
print(result.token)

Disable, revoke, or delete an existing key:

# Disable (reversible)
curl -X PATCH https://my.orq.ai/v2/api-keys/01HZXW2K7Y8Q9M0N1P2R3S4T5V \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "API_KEY_STATUS_DISABLED"}'

# Revoke (permanent)
curl -X PATCH https://my.orq.ai/v2/api-keys/01HZXW2K7Y8Q9M0N1P2R3S4T5V \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "API_KEY_STATUS_REVOKED"}'

# Delete
curl -X DELETE https://my.orq.ai/v2/api-keys/01HZXW2K7Y8Q9M0N1P2R3S4T5V \
  -H "Authorization: Bearer $ORQ_API_KEY"

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

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

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

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

# Revoke (permanent)
client.api_keys.update(
    api_key_id="01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    status="API_KEY_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.

Permission model

permission_mode selects the preset:

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

With PERMISSION_MODE_RESTRICTED, the access map assigns a level to each domain: ACCESS_LEVEL_NONE, ACCESS_LEVEL_READ, or ACCESS_LEVEL_WRITE. Write includes read. REST JSON accepts the enum names; the SDKs type the map as integers and use the numeric values:

Level	SDK value
`ACCESS_LEVEL_NONE`	1
`ACCESS_LEVEL_READ`	2
`ACCESS_LEVEL_WRITE`	3

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 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.

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://my.orq.ai/v2/api-keys \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Acme key",
    "project_scope": {
      "single": { "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V" }
    },
    "permission_mode": "PERMISSION_MODE_RESTRICTED",
    "access": {
      "agent": "ACCESS_LEVEL_WRITE"
    }
  }'

# Cap cost, tokens, and rate with a Budget scoped to the key
curl -X POST https://my.orq.ai/v2/budgets \
  -H "Authorization: Bearer $ORQ_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: {
    single: { projectId: "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V" },
  },
  permissionMode: "PERMISSION_MODE_RESTRICTED",
  access: {
    agent: 3,
  },
});

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={
        "single": {"project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V"},
    },
    permission_mode="PERMISSION_MODE_RESTRICTED",
    access={
        "agent": 3,
    },
)

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},
)

Overview

APIs

Routing

Security & Privacy

Model Capabilities

Analytics & Monitoring

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

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

​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

Permission model

The secret is returned once

Cost, token, and rate limits

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