Authentication

Every API request needs an API key. Keys belong to one workspace. Some of them carry scopes, which limit what the key can do on the Governance API.

API keys

Create keys under Settings → API Keys in the console. A key looks like this:

gsk_acme_8f2a1c9b7d6e5f4a3b2c1d0e9f8a7b6c

The middle segment is your workspace slug (acme above). Because the slug is in the key, the Agent API needs no slug in the path. For the Governance API, the slug in the path must match the slug in the key.

Treat keys like passwords. A key works for the whole workspace. Never commit one or put it in client-side code. The API is server-to-server.

Making an authenticated request

Send the key as a bearer token:

curl https://api.agenticcontrolplane.com/api/v1/agents \
  -H "Authorization: Bearer $ACP_KEY"

The Bearer prefix is optional, and a bare Authorization: gsk_… also works. Use Bearer anyway, since it is the convention.

import os, requests

ACP = "https://api.agenticcontrolplane.com"
headers = {"Authorization": f"Bearer {os.environ['ACP_KEY']}"}

r = requests.get(f"{ACP}/api/v1/agents", headers=headers)
r.raise_for_status()
print(r.json()["profiles"])

Scopes

Scopes limit what a key can do on the Governance API. The Agent API does not check scopes yet, so any valid key for the workspace can list, create, change, delete, and run agent profiles. Treat every key as having that access.

Scope	Status	Grants
`*`	Accepted	Full access. Use for your own automation, and avoid handing it out.
`admin.audit.read`	Enforced	Read the audit log.
`agents.write`	Reserved, not enforced yet	Intended for creating and changing agent profiles. Today any valid key can do this.
`agents.read`	Reserved, not enforced yet	Intended for listing and reading agent profiles. Today any valid key can do this.

admin.audit.read (or *) is the one scope checked today. A key without it gets 403 on the audit log. Policy changes are made by a signed-in owner or admin, not by a key. See Policies.

Human auth. The console signs you in with a session (a Firebase ID token), not a gsk_ key. Some governance endpoints accept either. This reference covers the API-key path, the one you will script against.

Base URLs

Surface	Base
Agents	`https://api.agenticcontrolplane.com/api/v1/agents`
Governance	`https://api.agenticcontrolplane.com/<workspace>/admin`

There is one production host. To keep testing separate, create a second workspace and a key for it. There is no sandbox URL.

Errors

A failed request returns a JSON body with one error field:

{ "error": "api key lacks admin.audit.read scope" }

Status	Meaning
`400`	Malformed request: a missing required field, bad JSON, or an invalid `since` timestamp.
`401`	Missing, malformed, or revoked key. Check the `Authorization` header and that the key is still active.
`403`	Authenticated, but the key’s scopes or the caller’s role don’t allow this.
`404`	The resource, usually an agent profile ID, doesn’t exist in this workspace.
`429`	Rate limited. Back off and retry (see below).
`500`	Something failed on our side. Safe to retry idempotent reads.

Branch on the status code, not on the error text. The text is for people and may change.

Rate limits

Mutating governance endpoints are rate limited and return 429 when you go over. Back off with exponential delay and jitter, then retry. Pace bulk jobs, such as seeding many policies or importing a fleet of agents, instead of sending them in parallel.

Versioning

The Agent API is versioned in its path (/api/v1). Within a major version we add fields and never repurpose or remove them. Ignore unknown keys in responses and an upgrade won’t break you. Breaking changes ship under a new version with notice.

Quickstart → Agents reference →