Skip to content
Cyoda Documentation
Settings

auth — authenticate client applications against cyoda

cyoda-go version 0.8.2

auth

Section titled “auth”

NAME

Section titled “NAME”

auth — authenticate client applications against cyoda.

GOAL

Section titled “GOAL”

Every cyoda API call needs an Authorization: Bearer <jwt> header. This page helps you decide how to get that JWT.

WHICH PATH DO I NEED?

Section titled “WHICH PATH DO I NEED?”
  • You have a client_id/secret you’ll manage in cyoda — use the M2M client + token endpoint. Read auth.clients then auth.tokens.
  • You have an existing IdP (Cognito, Keycloak, Auth0, …) — federate via OIDC. Read auth.oidc.
  • You have a key you sign tokens with yourself, no IdP — register a trusted key. Read auth.trusted-keys.
  • You have an M2M client acting on behalf of a user — use the token-exchange grant. Read the OBO section of auth.tokens.

Looking for OBO? The token-exchange (on-behalf-of) grant is documented as a section of auth.tokens — there is no separate auth.obo page. Run cyoda help auth tokens and read the token-exchange section.

Looking for env vars? All CYODA_OIDC_*, CYODA_IAM_*, CYODA_JWT_*, CYODA_HMAC_*, and CYODA_BOOTSTRAP_* knobs live in config.auth. Run cyoda help config auth.

TOKEN PRESENTATION

Section titled “TOKEN PRESENTATION”

All cyoda APIs accept the JWT via Authorization: Bearer <token>. The token claim shape — sub, iss, caas_org_id, caas_user_id, user_roles, caas_tier, exp, iat, jti, optionally act — is documented in auth.tokens.

SEE ALSO

Section titled “SEE ALSO”
  • config.auth — env-var reference for every auth knob
  • openapi — run cyoda help openapi tags for spec by tag, including OAuth and OIDC
  • errors.UNAUTHORIZED, errors.FORBIDDEN — universal auth-failure codes

Subtopics

Section titled “Subtopics”
  • cyoda help auth clients — auth.clients — provision and manage machine-to-machine (M2M) clients that authenticate against cyoda via the client_credentials grant.
  • cyoda help auth oidc — auth.oidc — register an external OIDC identity provider so JWTs it issues are accepted by cyoda directly, without re-minting at /oauth/token.
  • cyoda help auth tokens — auth.tokens — exchange credentials for a JWT at POST /api/oauth/token. Covers every supported grant and the canonical JWT claim contract that all cyoda tokens (M2M, OBO, federated OIDC, trusted-key) conform to.
  • cyoda help auth trusted-keys — auth.trusted-keys — register a public key with cyoda so JWTs you sign offline with the matching private key are accepted, without an IdP or /oauth/token round-trip.

See also

Section titled “See also”
  • cyoda help config auth — config.auth — IAM mode, JWT issuer, HMAC secret, and admin bootstrap controls.
  • cyoda help openapi — cyoda-go generates its OpenAPI 3.1 specification from the embedded api/openapi.yaml file compiled into the binary at build time. The spec is served at /openapi.json with runtime-patched server URLs. The Scalar API Reference UI is served at /docs and loads the spec from /openapi.json.
  • cyoda help errors UNAUTHORIZED — Returned when the Authorization header is missing, the bearer token is expired, the token signature is invalid, or the token was issued by an untrusted issuer. Also returned when a request reaches a protected route with no identity context established by the auth middleware.
  • cyoda help errors FORBIDDEN — The request was authenticated successfully but the caller’s JWT claims do not include the role required by the endpoint (for example, admin is required for administrative operations). Tenant mismatch — where the caller’s tenant does not match the resource — also produces this error.

Raw formats

Section titled “Raw formats”