Authentication

Keyraft uses Bearer token authentication. All endpoints except /v1/health and /v1/metrics require a valid token.

Bearer Token Header

Authorization: Bearer YOUR_TOKEN_HERE

Root Token

The root token is generated during keyrafted init. It has full administrative access. Store it securely and use it to create scoped tokens for applications.

Role-Based Access Control (RBAC)

Create tokens with predefined roles - the recommended approach:

curl -X POST http://localhost:7200/v1/auth/token \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "developer",
    "expires_in": 2592000,
    "metadata": {
      "name": "myapp-service",
      "description": "Token for myapp service"
    }
  }'

Available Roles

Role	Permissions
admin	Full access - manage tokens, roles, audit logs, namespaces
developer	Read, write, and delete in assigned namespaces
viewer	Read-only access to assigned namespaces
operator	Read, write, delete, and view audit logs in assigned namespaces

Legacy Scoped Access

For backward compatibility, you can create tokens with explicit namespace scopes:

curl -X POST http://localhost:7200/v1/auth/token \
  -H "Authorization: Bearer $ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": [
      {"namespace": "myapp/*", "read": true, "write": false}
    ],
    "expires_in": 2592000
  }'

Prefer RBAC roles for new tokens.

Token Management

List all tokens:

curl http://localhost:7200/v1/auth/tokens \
  -H "Authorization: Bearer $ROOT_TOKEN"

Revoke a token:

curl -X DELETE http://localhost:7200/v1/auth/token/TOKEN_VALUE \
  -H "Authorization: Bearer $ROOT_TOKEN"

Check current token identity:

curl http://localhost:7200/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Best Practices

• Use role-based tokens for applications (principle of least privilege)
• Set expiration on service tokens (expires_in in seconds)
• Revoke tokens when services are decommissioned
• Never commit tokens to source control

See also: API - Auth, API - Roles