Roles and API keys¶
The backend authenticates every request with Authorization: Bearer <credential>. The credential is one of:
- a session JWT from the UI (issuer
arnold-ui); - a JWT from another trusted issuer (
auth.jwt.issuers, by shared secret or JWKS); - a static API key (
auth.apiKeys).
With auth.dev.enabled, requests without a credential act as a development superadmin.
Roles¶
| Role | Granted to | Allows |
|---|---|---|
superadmin |
auth.admins, role mappings, dev user |
Admin page: sync controls, review metrics, token usage, permissions |
runner_execute |
runner key | Claim jobs, heartbeat, complete (/runner/v1/jobs) |
analysis_callback_write |
runner key | Report analysis progress/results, fetch persona snapshots, exchange Copilot execution keys |
smart_diff_callback_write |
runner key | Store story mode (smart diff) results |
review_feedback_write |
runner key | Ingest review feedback |
review_feedback_read |
Query review feedback (POST /review-feedback) |
|
backfill_review_feedback |
Housekeeping backfill of review feedback |
Signed-in users need no role for everyday features; what they can see and do on a forge is decided by their own forge permissions.
Admins and role mappings¶
local.yml
serviceCoreConfiguration:
auth:
admins: [alice@example.com, bob@example.com] # emails or user ids → superadmin (env: ARNOLD_ADMINS)
roleMappings: # group/org claim value → roles
arnold-admins: [superadmin]
quality-team: [review_feedback_read]
jwt:
userIdClaim: sub
emailClaim: email
nameClaim: name
rolesClaim: groups
clockSkewSeconds: 60
Groups come from the sign-in provider: the OIDC groupsClaim, or GitHub organization names when
allowedOrganizations is used.
API keys¶
local.yml
serviceCoreConfiguration:
auth:
apiKeys:
- name: runner
key: ${ARNOLD_RUNNER_API_KEY}
roles: [runner_execute, analysis_callback_write, smart_diff_callback_write, review_feedback_write]
- name: reporting
key: ${ARNOLD_REPORTING_API_KEY}
roles: [review_feedback_read]
Keys are configured only in the file (there is no UI). Use long random values and a separate key per consumer.
An entry with an empty key is ignored.