Authentication

Every request to the OverControl API uses an API key. This page shows where the key goes, which permission each endpoint needs, and what you’ll see when the key or the scope does not match.

Create a key

You create a key in the API dashboard. It starts with oc_sk_. Copy it when it appears, and keep it on your server.

export OVERCONTROL_API_KEY="your_api_key"

Treat the key like a password. It belongs on your server, not in client-side code, a repository, or a screenshot.

Where the key goes

You can pass the key in either of these headers. One of them is enough.

Authorization: Bearer $OVERCONTROL_API_KEY

x-api-key: $OVERCONTROL_API_KEY

If you send both, and x-api-key is not blank, OverControl uses that value and leaves Authorization unused. The bearer token is used when x-api-key is missing or empty.

Scopes

Each key carries a set of scopes. A request goes through when the key includes the scope for that operation.

Scope	What it allows
`chat:completions`	`POST /v1/chat/completions`
`messages:create`	`POST /v1/messages`
`models:read`	`GET /v1/models`
`files:write`	`POST /v1/files`
`files:read`	`GET /v1/files`, `GET /v1/files/:file_id`, and `GET /v1/files/:file_id/content`
`files:delete`	`DELETE /v1/files/:file_id`

If the scope is missing, you’ll get HTTP 403 and the message Forbidden. Chat Completions, the models list, and Files return this body. The response includes X-Request-Id.

{
  "error": {
    "message": "Forbidden",
    "type": "permission_error",
    "param": null,
    "code": "forbidden"
  }
}

Messages describes the same refusal in its own shape. You’ll also see request-id, and the same identifier inside the JSON as request_id.

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Forbidden"
  },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

Model allowlist

Some keys are limited to a list of model IDs. A key with no list can call every model on the models page, and GET /v1/models returns that full list. A key with a list only sees the models on it. If you call Chat Completions with a model the key is not allowed to use, you’ll get HTTP 403:

{
  "error": {
    "message": "Model 'lume-omni' is not allowed for this API key",
    "type": "permission_error",
    "param": null,
    "code": "forbidden"
  }
}

On Messages, an unknown model and a model outside the allowlist look the same. Both come back as HTTP 404:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Model not found"
  },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

When the key is not accepted

You’ll get HTTP 401 and the message Invalid API key if a request has missing key, a malformed Authorization value, and a key OverControl does not recognize. On Chat Completions, the models list, and Files:

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

On Messages:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

If you write to support about a failed call, include the X-Request-Id header. On Messages, request-id and request_id are that same value.

Get started

Text

Files

Migrate

Workspace

Integrations

Create a key

Where the key goes

Scopes

Model allowlist

When the key is not accepted

​Create a key

​Where the key goes

​Scopes

​Model allowlist

​When the key is not accepted

Create a key

Where the key goes

Scopes

Model allowlist

When the key is not accepted