Get started

Authentication

Every Runtime API and MCP call is authenticated with an organization-scoped API key. Keys never expire on a timer — rotate them by creating a new key and revoking the old one.

Create a key

Open Copia → Settings → API and click Create API key. Give it a descriptive name (usually the agent or workload that will use it). The secret is displayed exactly once.

Treat the secret like a password

Copia stores only a hash. If you lose the key, rotate it — there's no recovery flow.

Send the key

Either header works. Authorization: Bearer is the default for most agents; x-api-key is convenient when your client already has an Authorization header reserved for its own flows.

Authorization: Bearer

bash

curl https://copia-ai.com/api/runtime/capabilities \
  -H "Authorization: Bearer sk_live_copia_..."

x-api-key

bash

curl https://copia-ai.com/api/runtime/capabilities \
  -H "x-api-key: sk_live_copia_..."

Scopes

Keys carry one or more scopes. The Runtime API and MCP endpoint both require the runtime scope. New keys receive it by default.

runtimestringrequired
Required for Runtime API and MCP access. Allows the key to list capabilities, open sessions, invoke tools, and stream executions within the key's organization.
*stringoptional
Wildcard grant used by internal admin keys. Public keys do not receive this scope.

Error envelope

Missing, invalid, or under-scoped keys return a JSON body with an error field. The HTTP status tells you which case you're in.

Response body

json

{
  "error": "Invalid API key"
}

Status codes

401statusoptional
No key was provided, or the key does not exist.
403statusoptional
The key exists but is missing the runtime scope.

Rotating keys

Create the replacement first, update the client, then revoke the old one from Settings → API. Existing streams continue to run; new calls with a revoked key return 401.

MCP clients authenticate the same way. See MCP for per-client configuration snippets.

PreviousQuickstart NextCore concepts