Authentication

The v3 API is served at https://api.cademi.com.br/api/v3. It accepts HTTPS only and uses no cookies, sessions, or CSRF tokens. The credential, not the host, identifies the account: a credential issued for account A always operates on account A's data, whichever host you call.

Credentials

This is the common case: your integration calls the API on behalf of a system, with no person involved.

GET /api/v3/credentials/current
Authorization: Bearer ck_live_9f2c...

You can also send the secret in the X-API-Key header instead of Authorization. The secret is returned only once, when the credential is created, and no operation returns it again. Treat it like a password: the secret alone authenticates and authorizes calls. Sandbox secrets start with ck_test_. A credential always acts on its own, with the permissions of its policies.

GET /credentials/current tells you who you are: the credential ID, environment, and status. GET /capabilities lists the permissions in effect.

Administrators (OAuth)

An administrator can call the API as themself, with the OAuth access token issued by cademi auth login or by the Cademí MCP sign-in, sent alone:

GET /api/v3/users?limit=50
Authorization: Bearer <admin access token>

The request acts as that administrator, with the administrator's own permissions, and the audit trail shows the administrator in actor.admin_id. Never send the access token together with a credential secret: the API rejects the call with 401 ambiguous_credentials. No credential authenticates such a request, so GET /credentials/current returns 404 not_found; use GET /capabilities to read what the administrator can do. The authorization flow, the OAuth endpoints, and token renewal are covered in Administrators (OAuth).

Headers

Header	Direction	Purpose
`Authorization: Bearer <secret>` or `X-API-Key: <secret>`	request	Credential. Never send it in the query string, body, or a cookie.
`Authorization: Bearer <access token>`	request	Administrator, with the OAuth access token alone.
`Idempotency-Key`	request	Required on every `POST` that has side effects; accepted on `PATCH`, `PUT`, and `DELETE`. See Asynchronous operations, batches, and idempotency.
`If-Match`	request	Conditional write based on the resource revision. See Pagination, filtering, and conditional requests.
`Accept-Language`	request	Language of `error.message` and other human-readable text. Defaults to `en-US`.
`Content-Type: application/json`	request	Required when the request has a body. Any other type returns `415`. The v3 API never accepts file bytes.
`X-Client`, `X-Client-Version`, `X-Client-Install-Id`	request	Identify your client in the audit trail. They do not grant any access.
`X-Request-Id`	response	Identifier of the call, the same value as `error.request_id` and the audit entry.
`X-Cademi-Release`	response	Contract release that served the response, for example `3.2.0`.
`X-Cademi-Environment`	response	`production` or `sandbox`.
`Retry-After`	response	Seconds to wait before retrying after a `429` (and after a `503` when the wait is known). See Limits, quotas, and retention.
`Deprecation`, `Sunset`	response	The operation or field is deprecated. See Versioning and compatibility.

Authentication failures

Code	When
`unauthenticated`	No credential was sent, its format is not recognized, or the credential does not exist.
`credential_revoked`, `credential_suspended`, `credential_expired`	The credential exists but is no longer valid.
`invalid_access_token`	The administrator's access token is not valid, or its administrator was removed, moved to another account, or revoked.
`ambiguous_credentials`	The call sends an access token together with a credential secret, or an ID token instead of an access token.
`instance_blocked`	The account is blocked. Nothing is counted against your rate limit.

All of these return 401, except instance_blocked, which returns 403. The full list is in Errors.

First call

Create a credential in your Cademí dashboard and store the secret.
Publish a policy with the permissions your integration needs (Permissions and scope).
Confirm with GET /credentials/current, then continue with Examples.