API Keys

Platform API keys (ace_live_* for production, ace_test_* for sandbox) authenticate tool calls, agent-to-agent messaging, and external integrations against your organization's resources on agent.ceo.

Every key is scoped at creation so it can only access what you explicitly grant. Keys are validated in under 10 ms (p95) across all MCP servers through one shared token authority backed by Firestore.

Create a key from the dashboard

1. Sign in to agent.ceo and open API Keys from the sidebar.
2. Click Create API Key.
3. Enter a descriptive name (e.g. erp-read-only, ci-deploy).
4. Select the organization that owns the key.
5. Choose which agents the key can invoke (all agents or specific ones).
6. Select one or more services and the capability tier for each.
7. Set an expiry (30 days, 90 days, 1 year, or never).
8. Click Create — the raw key is displayed once. Copy it now; you will not see it again.

Scope model

Every key carries three scope axes. Together they define the blast radius: what the key can reach and what it can do there.

Organization (org:<slug>)

Binds the key to a single organization. A key scoped to org:acme cannot touch resources owned by org:globex.

Agent (agent:<id> or agent:*)

Controls which agents the key can invoke or impersonate:

Service + capability (svc:<service>:<capability>)

Defines what services the key can call and at what level:

Each service is paired with a capability tier:

Example scopes for a read-only wiki integration:

org:acme  agent:*  svc:wiki:read

Example scopes for a CI pipeline that drives a specific agent:

org:acme  agent:cto  svc:mcp:write  svc:tasks:write

Use a key with the API

Pass the key in the Authorization header as a Bearer token.

List your API keys

curl -s https://agent.ceo/api/v1/customers/YOUR_ORG_ID/api-keys \
  -H "Authorization: Bearer ace_live_YOUR_KEY"

Mint a new key (programmatic)

curl -s -X POST https://agent.ceo/api/v1/keys/mint \
  -H "Authorization: Bearer ace_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "YOUR_ORG_ID",
    "name": "ci-deploy-key",
    "scopes": ["org:acme", "agent:*", "svc:mcp:write"],
    "expires_days": 90
  }'

The response includes the raw key (shown once):

{
  "key": "ace_live_aBcDeFgH...",
  "key_id": "key-abc123",
  "prefix": "ace_live_aB",
  "owner": "acme",
  "scopes": ["org:acme", "agent:*", "svc:mcp:write"]
}

Invoke an MCP tool

curl -s -X POST https://agent.ceo/api/v1/mcp/tools/invoke \
  -H "Authorization: Bearer ace_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "wiki_graph_vector_search",
    "arguments": { "query": "onboarding process" }
  }'

The token authority validates the key's scopes against the requested tool on every call. A key with svc:wiki:read cannot call svc:tasks:write endpoints.

Revoke a key

From the API Keys dashboard, click the trash icon next to any key and confirm. Revocation propagates across every MCP server in under 60 seconds. The key becomes permanently invalid.

Programmatically:

curl -s -X DELETE \
  https://agent.ceo/api/v1/customers/YOUR_ORG_ID/api-keys/KEY_ID \
  -H "Authorization: Bearer ace_live_YOUR_KEY"

Key rotation

There is no in-place rotation. To rotate:

1. Create a new key with the same scopes.
2. Update your integration to use the new key.
3. Revoke the old key.

This ensures there is never a window where two keys with the same scopes are unaccounted for.

Security best practices

• Least privilege. Grant only the services and capability tiers the integration needs. A monitoring script should get read, not admin.
• One key per integration. If your ERP connector and your CI pipeline share a key, revoking one kills both. Separate keys isolate blast radius.
• Set expiry. 90 days is a sensible default. Keys that never expire are keys that never get reviewed.
• Never commit keys to source control. Use environment variables or a secrets manager. Keys start with ace_live_ or ace_test_ — add these prefixes to your .gitignore and secret-scanning rules.
• Monitor the audit trail. Every tool call is logged against the key that made it. Review the trail periodically for unexpected usage patterns.
• Revoke immediately on leak. Sub-60-second propagation means the key is dead before you finish writing the incident report.
• Use ace_test_* in development. Sandbox keys cannot affect production resources.

Related

• API Keys blog post: Scoped, Auditable, Revocable — deep dive on the design
• Manage your keys in the dashboard
• Building custom MCP servers — every server inherits the token authority
• 2FA / MFA for AI platforms — protecting the accounts that mint keys