Management APIs

The Management APIs are the workspace administration surface of the Orq.ai platform: programmatic control over the resources that govern how a workspace runs, including API Keys, Management Keys, Budgets, Projects, Alerts, Notifiers, Identities, Workspaces, Workspace Settings, Workspace Security, and Workspace Models.

Management plane vs data plane

The platform separates administration from inference into two planes:

Management plane: workspace administration. Endpoints live under /v2/ and authenticate with a workspace-scoped Management Key or a standard API Key, depending on the endpoint family (see the table below).
Data plane: inference and product endpoints. Requests run through the AI Gateway at https://my.orq.ai/v3/router and authenticate with a project-scoped API Key.

Management Keys manage workspace resources but cannot query models or agents; the data plane accepts only standard API Keys.

Base URL and versioning

Management endpoints use the platform base URL with the /v2/ version prefix:

URL

https://my.orq.ai/v2

The AI Gateway data plane uses /v3/ instead, for example https://my.orq.ai/v3/router/responses.

Resources

API Keys

Create, list, retrieve, update, and delete project-scoped keys, and fetch the capability catalog.

Management Keys

Create and manage workspace-scoped keys with per-domain access, plus the management capability catalog.

Budgets

Cap cost, token, and requests-per-minute usage per workspace, project, identity, key, provider, or model.

Projects

Organize keys, prompts, and models into projects and manage project lifecycle.

Alerts

Configure alert triggers and route notifications when thresholds are hit.

Notifiers

Identities

Track end users across projects and scope budgets and annotations to them.

Workspaces

List the workspaces a key can reach, and retrieve or update the workspace itself.

Workspace Settings

Retrieve and update workspace-level settings.

Workspace Security

Manage the verified domains and IP allowlist entries that gate workspace access.

Workspace Models

Enable a model for the workspace, or disable it again.

Each endpoint family requires a specific key type:

Resource	Endpoint family	Key type
API Keys	`/v2/api-keys*`	Management Key
Management Keys	`/v2/management-keys*`	Management Key
Budgets	`/v2/budgets*`	Management Key
Projects	`/v2/projects*`	Management Key (an all-projects API Key also works)
Alerts	`/v2/alerts*`	API Key
Notifiers	`/v2/notifiers*`	API Key or Management Key
Identities	`/v2/identities*`	API Key
Workspaces	`/v2/workspaces*`	Management Key (an all-projects API Key also works)
Workspace Settings	`/v2/workspace-settings*`	Management Key (an all-projects API Key also works)
Workspace Security	`/v2/workspaces/{workspace_key}/*`	Management Key (an all-projects API Key also works)
Workspace models	`/v2/workspace-models*`	Management Key

Authentication and permissions

Every key has a permission_mode preset and an optional per-domain access map:

All: full read and write access to every capability.
Read only: read access to every capability.
Restricted: per-domain access from the access map.

API Keys send lowercase strings: permission_mode is all, read_only, or restricted, and access values are none, read, or write. Management Keys send the enum names: MANAGEMENT_PERMISSION_MODE_* and ACCESS_LEVEL_*. The capability catalogs enumerate the grantable domains:

See API Keys and Management Keys for the permission presets and Management Keys for the workspace administration endpoints.

Worked example: provision a scoped key with a budget

The common automation task: mint a restricted Management Key, create a scoped API Key with it, then attach a Budget to cap the key’s spend.

Create a restricted Management Key

curl -X POST https://my.orq.ai/v2/management-keys \
  -H "Authorization: Bearer $ORQ_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-automation",
    "permission_mode": "MANAGEMENT_PERMISSION_MODE_RESTRICTED",
    "access": {
      "api-key": "ACCESS_LEVEL_WRITE",
      "budget": "ACCESS_LEVEL_WRITE"
    }
  }'

The response returns the token once; store it securely and use it as the bearer credential for the remaining requests.

Create a scoped API Key

curl -X POST https://my.orq.ai/v2/api-keys \
  -H "Authorization: Bearer $MANAGEMENT_KEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-gateway",
    "permission_mode": "restricted",
    "access": {
      "responses": "write",
      "model": "read"
    }
  }'

The response includes the key id and its token. Substitute the id for <api-key-id> in the next step.

Attach a Budget to the key

curl -X POST https://my.orq.ai/v2/budgets \
  -H "Authorization: Bearer $MANAGEMENT_KEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": {
      "api_key": {
        "api_key_id": "<api-key-id>"
      }
    },
    "limits": {
      "amount": 100,
      "period": "BUDGET_PERIOD_MONTHLY"
    }
  }'

For the available limit types and periods, see Budgets.

Orq SDK

Terminal & Agents

Terraform

Platform APIs

Management APIs

Management plane vs data plane

Base URL and versioning

Resources

API Keys

Management Keys

Budgets

Projects

Alerts

Notifiers

Identities

Workspaces

Workspace Settings

Workspace Security

Workspace Models

Authentication and permissions

Worked example: provision a scoped key with a budget

​Management plane vs data plane

​Base URL and versioning

​Resources

API Keys

Management Keys

Budgets

Projects

Alerts

Notifiers

Identities

Workspaces

Workspace Settings

Workspace Security

Workspace Models

​Authentication and permissions

​Worked example: provision a scoped key with a budget

Management plane vs data plane

Base URL and versioning

Resources

Authentication and permissions

Worked example: provision a scoped key with a budget