Authentication

The Canverly Public API authenticates every request with a per-site API key sent as an HTTP Bearer token.

Bearer token format

All requests must include the Authorization header:

Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key prefixes:

Prefix	Environment
ck_live_	Production (api.canverly.com)
ck_test_	Staging / HML

The key body after the prefix is 32 URL-safe characters (≈ 192 bits of entropy). Keys are opaque: do not try to parse them — Canverly stores only a hash and reserves the right to change the encoding.

Missing or malformed Authorization headers return 401 Unauthorized with:

{
  "type": "https://docs.canverly.com/errors/unauthenticated",
  "title": "Authentication required",
  "status": 401
}

Where the key is shown

When you click Gerar chave in Configurações → Integrações API → API Keys, the full secret is displayed exactly once in a modal with a Copy button. After closing the modal the secret is no longer retrievable — only its prefix (ck_live_xxxx...), name, scopes, and last-used-at timestamp are visible.

If you lose a key, revoke it and create a new one — there is no “show again” path. This is deliberate: the admin DB only stores a salted hash of the secret.

Revoking a key

In Configurações → Integrações API → API Keys, click the trash icon next to the key. Revocation is immediate — the next request using that key will return 401. There is no soft-delete; revoked keys are not recoverable.

For incident response, you can also rotate by:

1. Generating a new key with the same scopes.
2. Updating the consumer (Chimpee, your CMS bridge, etc.) to use the new key.
3. Revoking the old key once you confirm the consumer is on the new one.

Scopes

A key carries one or more scopes. The minimum scope set for a use case:

Scope	Grants	Typical use case
posts:read	GET /v1/posts, GET /v1/posts/{id}	Read-only sync / monitoring
posts:write	POST /v1/posts, PATCH /v1/posts/{id}, DELETE /v1/posts/{id}	Autoposters (Chimpee, Zapier, custom CMS bridges)
post_types:read	GET /v1/post-types	Schema discovery — strongly recommended alongside posts:write
sites:read	GET /v1/sites/me	Bootstrapping (resolve the site domain, theme, locale)

A request whose endpoint requires a scope the key does not have returns 403 Forbidden:

{
  "type": "https://docs.canverly.com/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "required_scope": "posts:write"
}

Key hygiene

• Never commit a key to a public repo. If you do, revoke it immediately — leaked keys are an audit-loggable event.
• Use separate keys for separate consumers so you can revoke one without breaking the others.
• The last_used_at column in the admin shows the last successful API call per key — use it to clean up dormant integrations.