API keys
API keys connect trusted backends and local stdio MCP clients to your organization. Hosted MCP uses browser OAuth and does not require you to give the client an API key. Each API credential has a public clr_pk_ key ID and a clr_sk_ secret. You need both for HMAC authentication. The secret is not a Bearer token or an owner wallet key.
Create and activate access#
- Complete organization onboarding, including the business profile and deployed Safe.
- Open API-key settings in the dashboard as the organization owner.
- Give the integration a descriptive name, select the needed scopes, and choose an expiry appropriate for the integration.
- Save the key ID and one-time secret in your backend's secret manager. Key listings never return the full secret again.
- If write activation is required, review and sign the Safe session activation through the owner flow. A created key with pending write access cannot yet issue or cancel invoices through the server signer. Pending does not resolve on its own: until you choose Finish activation in Settings → API Keys and sign, write access stays off. If activation cannot be prepared or the pending signer has expired, choose Start over and create a new write-scope key.
- Verify connectivity with the read-only example before deliberately issuing an invoice.
Requested expiry is 1 through 365 days, or no requested expiry. Write keys are also bounded by the underlying signer's session expiry. Check activation and expiry separately; a listed active revocation status is not proof that an expired credential will authenticate.
Scopes and their current boundary#
| Scope | Intended integration use |
|---|---|
invoice:read | Invoice reads |
invoice:write | Server-signed issue/cancel and invoice email; implies invoice read |
customer:read | Customer reads |
customer:write | Customer creation/update/delete; implies customer read |
dashboard:read | Organization, balance, and invoice-stat reads through /studios/me |
Scope enforcement is incomplete on legacy routes. A read-labeled key is not a complete read-only security boundary: some legacy routes, including share/token mutations, authenticate and check ownership without checking granular scope. Use keys only in trusted services, restrict the endpoints your integration calls, and consult the actual authorization matrix. Do not distribute a credential to an untrusted client based only on its scope labels.
The invoice server signer is independently restricted to invoice operations. It cannot sign an owner withdrawal or arbitrary Safe transaction. Owner-only key/signer/agent management requires a Privy JWT.
Rotate or revoke#
- Rotate secret if a trusted integration needs a replacement credential. The key ID stays the same; the old secret stops working immediately. Update the secret manager and restart/reload the integration. Rotation is not a dual-secret overlap period.
- Revoke key to terminate that credential's HTTP access. This differs from revoking the shared on-chain signer.
- Revoke signer to remove the shared invoice session through the owner-signed on-chain flow. Associated write access is affected across integrations using that signer.
- Force revoke signer is a database-only fallback. It disables server use but leaves the on-chain session installed. Do not describe it as completed on-chain revocation.
For named integrations, see agents. Unlinking a key from an agent does not revoke the key.
Operational checks#
Keep keys out of browser bundles, source control, logs, screenshots, and prompts. Use separate credentials for integrations and environments. Preserve operation IDs, invoice IDs, and transaction hashes for reconciliation, but avoid logging secrets and tokenized share URLs.
API-key activity is sampled, not a complete request-by-request audit. An absent activity entry does not prove a credential was unused. Maintain your own operational records if complete accounting or audit trails are needed. See management endpoints, errors and retries, and security.