Authorization API reference

Authorization query endpoints

Validate a resource name

Use this endpoint for real-time validation of project or role names before creation.

GET /api/v1/authz/validate_name?name=my-role&resource_type=role

Names must start and end with a letter or digit, and may contain letters, digits, colons, hyphens, and underscores. Maximum length is 255 characters. This endpoint requires authentication but does not require any specific permission.

Example response (valid):

{
  "valid": true,
  "name": "my-role",
  "reason": ""
}

Example response (invalid):

{
  "valid": false,
  "name": "-invalid",
  "reason": "Name must start and end with a letter or digit, and may contain letters, digits, colons, hyphens, and underscores"
}

Role management endpoints

Query parameters: limit, cursor, include_total, sort, name, is_builtin, project_id

Built-in roles (is_builtin: true) cannot be modified or deleted.

Create a custom role:

curl -X POST https://orchestrator.example.com/api/v1/roles \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workflow-operator",
    "description": "Can read and execute workflows",
    "policies": [
      "workflow:read:project",
      "execution:read:project",
      "execution:run:project"
    ],
    "labels": {},
    "project_id": "project-id"
  }'

Response: 201 Created with RoleRead (id, name, description, policies, is_builtin, is_system_scoped, project_id, labels, created_at, updated_at).

The is_system_scoped field is a computed boolean: true when the role is not scoped to a specific project.

Policy endpoints

Automation orchestrator ships built-in policies only. You cannot create, update, or delete policies. Use these endpoints to list and inspect built-in policies when you build custom roles.

Query parameters: limit, cursor, include_total, sort, name, is_builtin, project_id, project_eligible

The project_eligible filter returns policies that you can assign to project roles.

PolicyRead includes two computed fields:

• is_system_scoped — true when the policy is not scoped to a specific project.
• is_project_eligible — true when the policy can be used in project-scoped role assignments.

Role assignment endpoints

Use these endpoints to assign and remove roles for users and groups. Each role assignment targets either a user or service account (by principal_id) or a group (by group_id). Exactly one of principal_id or group_id must be provided.

Global role assignments:

Query parameters: principal_id, group_id, principal_name, role_name, project_id, limit, cursor, include_total, sort

Sub-resource role assignments (user-scoped):

Sub-resource role assignments (group-scoped):

Role assignment response fields:

Directory lookup endpoints

Use these endpoints for lightweight user and group lookups during role assignment workflows. Directory endpoints return only identifiers and names, avoiding PII exposure from the full user and group endpoints.

Query parameters: limit, cursor

The role assignment UI uses directory endpoints for user and group selection. Full user and group detail endpoints (/api/v1/users, /api/v1/groups) require the admin or auditor role.

Error response format

Authorization errors use the RFC 9457 Problem Details format with content type application/problem+json. The type field uses the https://api.example.com/errors/ URL prefix.

{
  "type": "https://api.example.com/errors/forbidden",
  "title": "Forbidden",
  "detail": "You do not have permission to access this resource",
  "code": "AUTHORIZATION_DENIED",
  "retryable": false,
  "instance": "/api/v1/role_assignments"
}