{
  "topic": "config.auth",
  "path": [
    "config",
    "auth"
  ],
  "title": "auth configuration",
  "synopsis": "config.auth — IAM mode, JWT issuer, HMAC secret, and admin bootstrap controls.",
  "body": "# config.auth\n\n## NAME\n\nconfig.auth — IAM mode, JWT issuer, HMAC secret, and admin bootstrap controls.\n\n## SYNOPSIS\n\ncyoda supports two IAM modes: `mock` (development) and `jwt` (production). Configure the\nmode via `CYODA_IAM_MODE`. Use `CYODA_REQUIRE_JWT` as a production safety guard to refuse\nstartup unless JWT mode is properly configured.\n\n## OPTIONS\n\n### IAM mode\n\n- `CYODA_IAM_MODE` — authentication mode: `mock` or `jwt` (default: `mock`)\n- `CYODA_REQUIRE_JWT` — refuse to start unless `jwt` mode is active and a signing key is set\n  (default: `false`)\n\n### Mock mode (`CYODA_IAM_MODE=mock`)\n\n- `CYODA_IAM_MOCK_ROLES` — comma-separated default user roles assigned to all requests\n  in mock mode (default: `ROLE_ADMIN,ROLE_M2M`)\n\n### JWT mode (`CYODA_IAM_MODE=jwt`)\n\n- `CYODA_JWT_SIGNING_KEY` — RSA private key in PEM format; required in jwt mode\n- `CYODA_JWT_SIGNING_KEY_FILE` — file path for `CYODA_JWT_SIGNING_KEY` (takes precedence)\n- `CYODA_JWT_ISSUER` — JWT issuer claim (`iss`) (default: `cyoda`)\n- `CYODA_JWT_AUDIENCE` — required audience claim (`aud`) on inbound JWTs;\n  empty string disables the audience check (default: empty)\n- `CYODA_JWT_EXPIRY_SECONDS` — token lifetime in seconds (default: `3600`)\n\n### HMAC secret (inter-node dispatch authentication)\n\n- `CYODA_HMAC_SECRET` — hex-encoded HMAC secret for inter-node dispatch auth\n- `CYODA_HMAC_SECRET_FILE` — file path for `CYODA_HMAC_SECRET` (takes precedence)\n\n### Bootstrap M2M client\n\ncyoda can provision a machine-to-machine client at startup for automation and CI.\n\n- `CYODA_BOOTSTRAP_CLIENT_ID` — bootstrap M2M client ID (optional)\n- `CYODA_BOOTSTRAP_CLIENT_SECRET` — bootstrap M2M client secret; must be set when\n  `CYODA_BOOTSTRAP_CLIENT_ID` is set (and vice versa)\n- `CYODA_BOOTSTRAP_CLIENT_SECRET_FILE` — file path for `CYODA_BOOTSTRAP_CLIENT_SECRET`\n  (takes precedence)\n- `CYODA_BOOTSTRAP_TENANT_ID` — tenant for the bootstrap client (default: `default-tenant`)\n- `CYODA_BOOTSTRAP_USER_ID` — user ID for the bootstrap client (default: `admin`)\n- `CYODA_BOOTSTRAP_ROLES` — comma-separated roles granted to the bootstrap client\n  (default: `ROLE_ADMIN,ROLE_M2M`)\n\n## EXAMPLES\n\n**Development (mock auth):**\n\n```\nCYODA_IAM_MODE=mock\nCYODA_IAM_MOCK_ROLES=ROLE_ADMIN,ROLE_M2M\n```\n\n**Production (JWT auth):**\n\n```\nCYODA_IAM_MODE=jwt\nCYODA_REQUIRE_JWT=true\nCYODA_JWT_SIGNING_KEY_FILE=/etc/secrets/signing.pem\nCYODA_JWT_ISSUER=https://auth.example.com\nCYODA_JWT_AUDIENCE=cyoda-api\nCYODA_JWT_EXPIRY_SECONDS=3600\n```\n\n**With bootstrap client:**\n\n```\nCYODA_BOOTSTRAP_CLIENT_ID=ci-client\nCYODA_BOOTSTRAP_CLIENT_SECRET_FILE=/etc/secrets/ci-secret\nCYODA_BOOTSTRAP_ROLES=ROLE_ADMIN,ROLE_M2M\n```\n\n## SEE ALSO\n\n- config\n- run\n",
  "sections": [
    {
      "name": "NAME",
      "body": "config.auth — IAM mode, JWT issuer, HMAC secret, and admin bootstrap controls."
    },
    {
      "name": "SYNOPSIS",
      "body": "cyoda supports two IAM modes: `mock` (development) and `jwt` (production). Configure the\nmode via `CYODA_IAM_MODE`. Use `CYODA_REQUIRE_JWT` as a production safety guard to refuse\nstartup unless JWT mode is properly configured."
    },
    {
      "name": "OPTIONS",
      "body": "### IAM mode\n\n- `CYODA_IAM_MODE` — authentication mode: `mock` or `jwt` (default: `mock`)\n- `CYODA_REQUIRE_JWT` — refuse to start unless `jwt` mode is active and a signing key is set\n  (default: `false`)\n\n### Mock mode (`CYODA_IAM_MODE=mock`)\n\n- `CYODA_IAM_MOCK_ROLES` — comma-separated default user roles assigned to all requests\n  in mock mode (default: `ROLE_ADMIN,ROLE_M2M`)\n\n### JWT mode (`CYODA_IAM_MODE=jwt`)\n\n- `CYODA_JWT_SIGNING_KEY` — RSA private key in PEM format; required in jwt mode\n- `CYODA_JWT_SIGNING_KEY_FILE` — file path for `CYODA_JWT_SIGNING_KEY` (takes precedence)\n- `CYODA_JWT_ISSUER` — JWT issuer claim (`iss`) (default: `cyoda`)\n- `CYODA_JWT_AUDIENCE` — required audience claim (`aud`) on inbound JWTs;\n  empty string disables the audience check (default: empty)\n- `CYODA_JWT_EXPIRY_SECONDS` — token lifetime in seconds (default: `3600`)\n\n### HMAC secret (inter-node dispatch authentication)\n\n- `CYODA_HMAC_SECRET` — hex-encoded HMAC secret for inter-node dispatch auth\n- `CYODA_HMAC_SECRET_FILE` — file path for `CYODA_HMAC_SECRET` (takes precedence)\n\n### Bootstrap M2M client\n\ncyoda can provision a machine-to-machine client at startup for automation and CI.\n\n- `CYODA_BOOTSTRAP_CLIENT_ID` — bootstrap M2M client ID (optional)\n- `CYODA_BOOTSTRAP_CLIENT_SECRET` — bootstrap M2M client secret; must be set when\n  `CYODA_BOOTSTRAP_CLIENT_ID` is set (and vice versa)\n- `CYODA_BOOTSTRAP_CLIENT_SECRET_FILE` — file path for `CYODA_BOOTSTRAP_CLIENT_SECRET`\n  (takes precedence)\n- `CYODA_BOOTSTRAP_TENANT_ID` — tenant for the bootstrap client (default: `default-tenant`)\n- `CYODA_BOOTSTRAP_USER_ID` — user ID for the bootstrap client (default: `admin`)\n- `CYODA_BOOTSTRAP_ROLES` — comma-separated roles granted to the bootstrap client\n  (default: `ROLE_ADMIN,ROLE_M2M`)"
    },
    {
      "name": "EXAMPLES",
      "body": "**Development (mock auth):**\n\n```\nCYODA_IAM_MODE=mock\nCYODA_IAM_MOCK_ROLES=ROLE_ADMIN,ROLE_M2M\n```\n\n**Production (JWT auth):**\n\n```\nCYODA_IAM_MODE=jwt\nCYODA_REQUIRE_JWT=true\nCYODA_JWT_SIGNING_KEY_FILE=/etc/secrets/signing.pem\nCYODA_JWT_ISSUER=https://auth.example.com\nCYODA_JWT_AUDIENCE=cyoda-api\nCYODA_JWT_EXPIRY_SECONDS=3600\n```\n\n**With bootstrap client:**\n\n```\nCYODA_BOOTSTRAP_CLIENT_ID=ci-client\nCYODA_BOOTSTRAP_CLIENT_SECRET_FILE=/etc/secrets/ci-secret\nCYODA_BOOTSTRAP_ROLES=ROLE_ADMIN,ROLE_M2M\n```"
    },
    {
      "name": "SEE ALSO",
      "body": "- config\n- run"
    }
  ],
  "see_also": [
    "config",
    "run"
  ],
  "stability": "stable",
  "actions": []
}