Users and API keys

The users file (--users) holds local users, service API keys and role mappings for SSO identities. It reloads on SIGHUP.

Authorization header	Method	Roles come from
Basic base64(user:password)	local user	users[].roles
Bearer curral_...	API key	api_keys[].roles
Bearer <JWT>	OIDC token	the token, see OIDC

Local users

Generate a bcrypt hash; the file never stores the password:

curral hash-password
# or: docker run --rm -it lucasapassos/curral hash-password

users:
  - name: analyst
    password_hash: "$2a$10$..."
    roles: [analyst]

Verified passwords are cached for --auth-cache-ttl (default 5 minutes). A reload drops the cache, so removed users lose access immediately.

API keys

For jobs and services. The key is printed once, together with the entry for the users file, which stores only its SHA-256:

curral gen-api-key etl-job etl

api_keys:
  - name: etl-job
    key_sha256: "49e4c3b9..."
    roles: [etl]
    expires: 2027-12-31     # optional

Clients send it as Authorization: Bearer curral_....

Roles are just names

curral does not define what a role means. Roles are strings passed to your policy, which decides what each one may do.

Failures

The client always gets a bare 401. The reason goes to the operational log, the audit log records auth_method (basic, api_key, jwt), and curral_auth_failures_total{method} counts failures. Repeated failures trigger a lockout.