{
  "topic": "auth",
  "path": [
    "auth"
  ],
  "title": "auth — authenticate client applications against cyoda",
  "synopsis": "auth — authenticate client applications against cyoda.",
  "body": "# auth\n\n## NAME\n\nauth — authenticate client applications against cyoda.\n\n## GOAL\n\nEvery cyoda API call needs an `Authorization: Bearer <jwt>` header. This page helps you decide how to get that JWT.\n\n## WHICH PATH DO I NEED?\n\n- **You have a `client_id`/`secret` you'll manage in cyoda** — use the M2M client + token endpoint. Read `auth.clients` then `auth.tokens`.\n- **You have an existing IdP (Cognito, Keycloak, Auth0, …)** — federate via OIDC. Read `auth.oidc`.\n- **You have a key you sign tokens with yourself, no IdP** — register a trusted key. Read `auth.trusted-keys`.\n- **You have an M2M client acting on behalf of a user** — use the token-exchange grant. Read the OBO section of `auth.tokens`.\n\n**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.\n\n**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`.\n\n## TOKEN PRESENTATION\n\nAll 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`.\n\n## SEE ALSO\n\n- `config.auth` — env-var reference for every auth knob\n- `openapi` — run `cyoda help openapi tags` for spec by tag, including OAuth and OIDC\n- `errors.UNAUTHORIZED`, `errors.FORBIDDEN` — universal auth-failure codes\n",
  "sections": [
    {
      "name": "NAME",
      "body": "auth — authenticate client applications against cyoda."
    },
    {
      "name": "GOAL",
      "body": "Every cyoda API call needs an `Authorization: Bearer <jwt>` header. This page helps you decide how to get that JWT."
    },
    {
      "name": "WHICH PATH DO I NEED?",
      "body": "- **You have a `client_id`/`secret` you'll manage in cyoda** — use the M2M client + token endpoint. Read `auth.clients` then `auth.tokens`.\n- **You have an existing IdP (Cognito, Keycloak, Auth0, …)** — federate via OIDC. Read `auth.oidc`.\n- **You have a key you sign tokens with yourself, no IdP** — register a trusted key. Read `auth.trusted-keys`.\n- **You have an M2M client acting on behalf of a user** — use the token-exchange grant. Read the OBO section of `auth.tokens`.\n\n**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.\n\n**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`."
    },
    {
      "name": "TOKEN PRESENTATION",
      "body": "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`."
    },
    {
      "name": "SEE ALSO",
      "body": "- `config.auth` — env-var reference for every auth knob\n- `openapi` — run `cyoda help openapi tags` for spec by tag, including OAuth and OIDC\n- `errors.UNAUTHORIZED`, `errors.FORBIDDEN` — universal auth-failure codes"
    }
  ],
  "see_also": [
    "config.auth",
    "openapi",
    "errors.UNAUTHORIZED",
    "errors.FORBIDDEN"
  ],
  "stability": "evolving",
  "actions": [],
  "children": [
    "auth.clients",
    "auth.oidc",
    "auth.tokens",
    "auth.trusted-keys"
  ]
}