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.
Autonomous mode
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...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_.
Human mode (OAuth plus credential)
When a call must be attributed to a real administrator (for example, a CLI or a third-party dashboard), issue the credential in human mode and send both values on every call:
GET /api/v3/users?limit=50
Authorization: Bearer <admin access token>
X-API-Key: ck_live_9f2c...Both values are validated, with no fallback: a revoked, suspended, or expired credential is rejected before the access token is checked. The administrator must belong to the same account as the credential and be linked to it. Human mode does not extend the credential's policy: authorization is still determined by the credential, and the administrator is recorded as the author in the audit trail. The authorization flow, the OAuth endpoints, and token renewal are covered in Human mode (OAuth).
GET /credentials/current tells you who you are: the credential ID, environment, mode, effective permissions and, in human mode, the human object with the administrator and its validity.
Headers
| Header | Direction | Purpose |
|---|---|---|
Authorization: Bearer <secret> | request | Autonomous mode. Never send it in the query string, body, or a cookie. |
Authorization: Bearer <access token> plus X-API-Key | request | Human mode. |
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. |
human_context_required | The credential requires human mode, but only the key was sent. |
invalid_access_token | The administrator's access token is not valid. |
ambiguous_credentials | The call mixes both modes, or sends an ID token instead of an access token. |
human_mode_not_allowed, tenant_mismatch, admin_not_eligible | The administrator and credential pair is not accepted. |
instance_blocked | The account is blocked. Nothing is counted against your rate limit. |
All of these return 401, except the three pair codes and instance_blocked, which return 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.