> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Management APIs

> Manage API keys, budgets, projects, alerts, notifiers, and identities programmatically through the Orq.ai Management APIs on the /v2 REST surface.

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](/reference/api-keys/create-a-new-api-key), [Management Keys](/reference/management-keys/create-a-new-management-key), [Budgets](/reference/budgets/create-a-new-budget), [Projects](/reference/projects/create-a-new-project), [Alerts](/reference/alerts/create-an-alert), [Notifiers](/reference/notifiers/create-a-notifier), [Identities](/reference/identities/create-an-identity), [Workspaces](/reference/workspaces/list-workspaces), [Workspace Settings](/reference/workspace-settings/retrieve-workspace-settings), [Workspace Security](/reference/workspace-security/list-verified-domains), and [Workspace Models](/reference/models/enable-model-for-workspace).

## 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](/ai-studio/organization/management-keys) or a standard [API Key](/ai-gateway/configuration/api-keys), 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](/ai-gateway/configuration/api-keys).

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:

```text URL theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://my.orq.ai/v2
```

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

## Resources

<CardGroup cols={3}>
  <Card title="API Keys" icon="key" href="/reference/api-keys/create-a-new-api-key">
    Create, list, retrieve, update, and delete project-scoped keys, and fetch the capability catalog.
  </Card>

  <Card title="Management Keys" icon="shield-check" href="/reference/management-keys/create-a-new-management-key">
    Create and manage workspace-scoped keys with per-domain access, plus the management capability catalog.
  </Card>

  <Card title="Budgets" icon="gauge" href="/reference/budgets/create-a-new-budget">
    Cap cost, token, and requests-per-minute usage per workspace, project, identity, key, provider, or model.
  </Card>

  <Card title="Projects" icon="folder" href="/reference/projects/create-a-new-project">
    Organize keys, prompts, and models into projects and manage project lifecycle.
  </Card>

  <Card title="Alerts" icon="bell" href="/reference/alerts/create-an-alert">
    Configure alert triggers and route notifications when thresholds are hit.
  </Card>

  <Card title="Notifiers" icon="plug" href="/reference/notifiers/create-a-notifier">
    Register webhook and channel targets that alerts and budgets notify.
  </Card>

  <Card title="Identities" icon="users" href="/reference/identities/create-an-identity">
    Track end users across projects and scope budgets and annotations to them.
  </Card>

  <Card title="Workspaces" icon="building" href="/reference/workspaces/list-workspaces">
    List the workspaces a key can reach, and retrieve or update the workspace itself.
  </Card>

  <Card title="Workspace Settings" icon="sliders" href="/reference/workspace-settings/retrieve-workspace-settings">
    Retrieve and update workspace-level settings.
  </Card>

  <Card title="Workspace Security" icon="shield" href="/reference/workspace-security/list-verified-domains">
    Manage the verified domains and IP allowlist entries that gate workspace access.
  </Card>

  <Card title="Workspace Models" icon="microchip" href="/reference/models/enable-model-for-workspace">
    Enable a model for the workspace, or disable it again.
  </Card>
</CardGroup>

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:

* [`GET /v2/api-keys/capabilities`](/reference/api-keys/list-capability-catalog)
* [`GET /v2/management-keys/capabilities`](/reference/management-keys/list-management-capability-catalog)

See [API Keys and Management Keys](/ai-gateway/configuration/api-keys) for the permission presets and [Management Keys](/ai-studio/organization/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.

<Steps>
  <Step title="Create a restricted Management Key">
    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      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"
          }
        }'
      ```
    </CodeGroup>

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

  <Step title="Create a scoped API Key">
    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      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"
          }
        }'
      ```
    </CodeGroup>

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

  <Step title="Attach a Budget to the key">
    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      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"
          }
        }'
      ```
    </CodeGroup>

    For the available limit types and periods, see [Budgets](/ai-gateway/budgets).
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.