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

> Programmatically manage API keys, budgets, projects, and other workspace resources through the Orq.ai management plane.

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), and [Identities](/reference/identities/create-an-identity).

## 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](/docs/ai-studio/organization/management-keys) or a standard [API Key](/docs/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://api.orq.ai/v3/router` and authenticate with a project-scoped [API Key](/docs/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://api.orq.ai/v2
```

The **AI Gateway** data plane uses `/v3/` instead, for example `https://api.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="broadcast" 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>
</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                                             |

## 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. Values are `ACCESS_LEVEL_NONE`, `ACCESS_LEVEL_READ`, or `ACCESS_LEVEL_WRITE`.

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](/docs/ai-gateway/configuration/api-keys) for the permission presets and [Management Keys](/docs/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://api.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://api.orq.ai/v2/api-keys \
        -H "Authorization: Bearer $MANAGEMENT_KEY_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "prod-gateway",
          "permission_mode": "PERMISSION_MODE_RESTRICTED",
          "access": {
            "responses": "ACCESS_LEVEL_WRITE",
            "model": "ACCESS_LEVEL_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://api.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](/docs/ai-gateway/budgets).
  </Step>
</Steps>