Authentication

Send the key as a Bearer token

Put the key Cantora issued into CANTORA_API_KEY, then send it in the Authorization header. These commands use Bash. Start a Bash session in this terminal and keep it open for the following request. Reading the value at a hidden prompt keeps the literal credential out of the shell command history.

bash

read -rsp "Cantora API key: " CANTORA_API_KEY
printf '\n'
export CANTORA_API_KEY

curl --fail-with-body https://api.cantora.ai/v1/identity \
  --header "Authorization: Bearer ${CANTORA_API_KEY}"

The /v1/identity response identifies the ServicePrincipal and Organization associated with the key. It does not grant authority by itself; the principal's active Grants govern every later request.

Treat the value as a one-time secret

Cantora returns a new API key in full once. Store it in an approved secret manager or CI secret store, never in source code, Agent Configuration, a plan artifact, or a log. A lost key cannot be recovered; replace it.

Rotate with overlap: issue the replacement, update and verify the caller, then revoke the predecessor. Never print either value to compare them. Unset a locally exported key when the session is finished:

unset CANTORA_API_KEY

Authentication is separate from authorization

• 401 Unauthorized means the Bearer header or credential was absent, malformed, expired, revoked, or otherwise invalid.
• 403 Forbidden means authentication succeeded, but the principal lacks the permission required at the requested scope.
• Some unauthorized cross-scope reads return 404 Not Found so the response does not reveal whether another scope contains the identifier.

See Errors for response shapes and retry guidance.