API keys and scopes
Creating an app mints an acp_-prefixed key with 24 random bytes. The raw value is returned once. ACP stores only its SHA-256 hash and a display prefix.
| Property | Current behavior |
|---|---|
| Default scope | ingest, read |
| Enforced on | POST /api/heartbeat and POST /api/report |
| Lifecycle | Keys support expiry and revocation timestamps. |
| Storage | SHA-256 hash only; the raw token is never persisted. |
| Prompt fetch | The SDK endpoint /api/prompts/:agentId requires a prompt-scoped key in x-api-key. The agent read endpoint /api/agents/:id/prompt uses read scope. |
Current scope boundary: API-key ingest scope and an app’s control scope are separate settings. The server enforces monitor, control, and full command scopes. Prompt updates require owner or admin approval. See control scopes for the exact boundary.
Secret placement
ACP_API_KEYbelongs only in the target app's server environment.ACP_WEBHOOK_SECRETis shared between ACP and the target app's webhook receiver.ACP_URLis not secret; set it to the public ACP origin.- Never put either secret in browser code, client bundles, logs, or support screenshots.