Authorization V1
The Authorization V1 integration service provides programmatic permission evaluation endpoints. It is used by other services to check whether a user is authorized to perform an action on a resource.
Service Definition
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /_integration/authorization/v1/evaluate | Evaluate a single permission |
POST | /_integration/authorization/v1/evaluate-many | Evaluate multiple permissions |
POST | /_integration/authorization/v1/evaluate-token | Evaluate from JWT token |
POST | /_integration/authorization/v1/evaluate-token-many | Batch evaluate from JWT token |
Evaluate
Checks if a user with given roles can perform an action on a resource.
Request:
{
"user": "alice",
"roles": ["viewer", "editor"],
"action": "collection:write",
"resource": "reports"
}
Response:
{
"message": "Access Granted",
"effect": "Allow"
}
EvaluateMany
Batch version — checks multiple action/resource pairs for the same user.
Request:
{
"user": "alice",
"roles": ["viewer"],
"items": [
{"action": "collection:read", "resource": "reports"},
{"action": "collection:write", "resource": "reports"}
]
}
EvaluateToken / EvaluateTokenMany
Same as Evaluate/EvaluateMany but takes a JWT token instead of explicit user and roles. The user and roles are extracted from the token claims.
RBAC Permissions
Beyond evaluating permissions, the authorization service also exposes the RBAC management API (roles, policies and user-role bindings) and the streaming pool endpoints that sidecars use to sync RBAC state. Each management call is itself authorized: the caller’s token must be granted the matching rbac:* action, via an ArangoPermissionPolicy bound to their role.
| Action | Resource |
|---|---|
rbac:ListRole, rbac:GetRole, rbac:CreateRole, rbac:UpdateRole, rbac:DeleteRole | the role name (empty for List) |
rbac:ListPolicy, rbac:GetPolicy, rbac:CreatePolicy, rbac:UpdatePolicy, rbac:DeletePolicy | the policy name (empty for List) |
rbac:ListUserRoleBinding, rbac:AssignUserRole, rbac:RemoveUserRole, rbac:ReplaceUserRoleScope | the target user |
rbac:PoolRole, rbac:PoolPolicy, rbac:PoolUserRoleBinding | (empty) — the streaming pool sidecars use to sync RBAC state |
The Evaluate / EvaluateToken endpoints above are not gated by an rbac:* action — they are the enforcement primitive other services call to authorize their own operations.
Forcing a refresh on evaluation (read-your-writes)
Each sidecar serves Evaluate from a locally cached copy of the RBAC pools that it streams from the pool service, so immediately after a policy/role/binding change a different sidecar (for example another coordinator) may still answer from a slightly stale cache until its stream catches up.
A caller that just changed RBAC state and must not observe that stale cache can set the gRPC request metadata header x-arangodb-authorization-refresh: true on any of Evaluate, EvaluateMany, EvaluateToken or EvaluateTokenMany. The service then re-pulls its pools (policies, roles and user/group role bindings) from the store before evaluating, giving read-your-writes consistency for that call. It is opt-in because it trades a little latency for consistency; the data-path callers (arangod / the gateway) do not set it. The header name is exported as authorization/v1/definition.RefreshHeader. It is equivalent to calling the Refresh RPC first, but scoped to the single evaluation and guaranteed to run on whichever sidecar serves it.
Configuration
The authorization mode is controlled by the INTEGRATION_AUTHORIZATION_V1_TYPE environment variable:
| Value | Behavior |
|---|---|
central | Full policy enforcement |
central-permissive | Evaluate but allow on error |
always | Always allow |
never | Always deny |
See RBAC for details on enabling and configuring authorization.