Skip to main content
Agnes has a scope-based authorization model with four built-in roles. Roles bundle scopes; scopes are the fine-grained capabilities the API enforces. You almost never need to think about scopes — pick a role and assign it to a user (for dashboard access) or an API key (for programmatic access). Scopes are exposed when you need them.

​
The four built-in roles

Member is the default role — every invitation lands as a member unless you explicitly grant something else.

​
What each role can do

Listed by feature area. ”—” means the role has no permission for that action. A member can run analyzers and author policies but cannot mint API keys — that intentionally keeps key issuance behind owner / admin review.

​
Scopes (advanced)

Roles are syntactic sugar over scopes. The shipped roles compose from this scope vocabulary:
  • tenant:create, tenant:read, tenant:update, tenant:delete, tenant:edit, tenant:read_stats, tenant:manage_users, tenant:invite_users, tenant:remove_users
  • role:create, role:read, role:update, role:delete, role:assign
  • policy:create, policy:read, policy:update, policy:delete
  • yara:create, yara:read, yara:update, yara:delete, yara:analyze, yara:generate
  • sdp:create, sdp:read, sdp:delete
  • safety_policy:create, safety_policy:read, safety_policy:update, safety_policy:delete
  • analyzer:run, dlp:analyze, nlp:analyze, url:analyze, vector:analyze, vector:manage_embeddings, safety_moderation:analyze, adversarial_prompt_detection:analyze
  • analyzer_logs:read, admin_logs:read
  • api_key:create, api_key:read, api_key:update, api_key:delete, api_key:read_usage
  • billing:catalog_read, billing:catalog_sync, billing:status_read, billing:subscribe, billing:payment_methods_read, billing:payment_methods_update, billing:plan_change, billing:invoices_read, billing:usage_report, billing:usage_read
The full list and current scope assignments are returned by GET /api/v1/api-keys/scopes (used by the dashboard key creator).

​
API keys and scopes

When minting an API key, you choose a subset of scopes for the key. The key cannot exceed its owning user’s role — a member cannot mint a key with api_key:create even if they edit the form. The dashboard disables scopes the user does not have. Recommended bundles:
  • Production analyzer key — analyzer:run, all *:analyze, analyzer_logs:read. Nothing else.
  • CI sandbox key — same as above plus policy:read if your CI needs to enumerate policies.
  • Admin / automation key — full analyzer scopes plus the policy / YARA / SDP / safety create-update-delete scopes you need.
  • Dashboard read-only key — every *:read scope. No mutations.

​
Custom roles (Owner only)

Owners can author custom roles with any combination of scopes. Useful when you want roles that do not fit the four defaults — e.g. “Compliance auditor” with all *:read scopes plus analyzer_logs:read and admin_logs:read but no mutations. Custom roles inherit nothing from the defaults; you start from an empty scope set and add what you need.

​
Forbidden vs unauthorized

A request that authenticates but lacks a required scope returns forbidden (403). A request with no authentication or invalid credentials returns unauthorized (401). The two are not interchangeable.

​
Next