Authentication - Blackswan

Token issuance is handled by a separate auth host. Every request to this API must include a valid JWT issued there in the Authorization header.

If you don’t have a token yet, head to Authorization for the credential and token-issuance flow first, then come back here for the per-call mechanics.

Headers

Authorization: Bearer <jwt>
Content-Type: application/json

Authorization rule

All partner-facing endpoints require the ADMIN role. A valid token whose subject lacks the role receives 403 permission_denied with sub_code: insufficient_role; a missing, malformed or expired token receives 401 unauthenticated. Refreshing the token fixes a 401, never a 403.

Token lifecycle

Tokens have a finite TTL set by the auth host.
Tokens are not refreshed by this API. When a token expires, obtain a new one from the auth host.
Revocation is handled at the auth host.

Common auth errors

Status	Code	Cause
401	`unauthenticated`	Missing, malformed, or expired token
403	`permission_denied` (`insufficient_role`)	Valid token, but the subject lacks the `ADMIN` role

Example

curl -sf "$BASE/v1/customers" \
  -H "Authorization: Bearer $TOKEN"

If you get 401 unauthenticated on a known-good token, the most common cause is that the token was issued by a different auth realm than the one this deployment trusts. Contact your integration representative to verify.