Determine required API permissions

Permission requirements

Every API endpoint that modifies or retrieves resources requires a specific resource:action permission. For example, creating a workflow requires the workflow:create permission, and triggering an execution requires execution:run.

Your effective permissions depend on the roles assigned to your user account, service account, or groups. Roles apply at the system level or within a specific project. Project-scoped roles grant permissions only within that project's resources.

The authorization model uses allow-only policies with a deny-by-default posture. If no policy grants a permission, the action is denied. There are no explicit deny rules.

Common permission sets for integration scenarios:

CI/CD pipeline integration

Requires workflow:read, execution:run, execution:read, and credential:use within the target project.

Workflow management automation

Requires workflow:create, workflow:read, workflow:update, and workflow:delete within the target project.

Read-only monitoring

Requires workflow:read and execution:read within the target project.

The credential:use permission separates credential consumption from credential management. A service account that runs workflows needs credential:use to reference credentials in workflow steps. It does not need credential:create or credential:update, which are required only to manage credential values. Credential use permissions are enforced at workflow save time, not at execution time.

Authentication and authorization failure responses

Your integration must distinguish between authentication failures (401) and authorization failures (403) and handle each appropriately:

401 Unauthorized

Your access token is missing, expired, or revoked. Refresh the access token by using the refresh endpoint and retry the request. If the refresh also fails, re-authenticate with credentials.

403 Forbidden

Your user account or service account lacks the required permission for this operation. Do not retry with the same credentials; the result is the same. Check the detail field in the error response to identify the missing permission.

Permission introspection endpoints

The automation orchestrator provides introspection endpoints that let your integration verify permissions before attempting an operation. Pre-checking permissions avoids unnecessary 403 responses and enables informative error messages.

The primary introspection endpoint is POST /api/v1/authz/can_i. It accepts the following fields in the request body:

• resource_type: The type of resource to check, such as workflow, execution, credential, or service_account.
• action: The action to check, such as create, read, or run.
• resource_project: The project scope as a project name or UUID.

The response indicates whether the authenticated user has the specified permission. Use this check before performing sensitive operations to fail fast with a clear error message.

Three additional introspection endpoints are available:

• POST /api/v1/authz/what_can_i: Returns a paginated list of all permissions assigned to your user, across all projects and system-level roles. Use this endpoint to discover what your integration can do without checking each permission individually.
• POST /api/v1/authz/who_can: Lists all users who have a specific permission. Useful for verifying which users can perform an action for auditing or role validation.
• GET /api/v1/authz/resource_actions: Returns the full catalog of resource types and their available actions. Use this endpoint to discover valid resource_type and action combinations for the can_i endpoint.

List endpoints automatically filter results based on your permissions. If you have workflow:read permission in Project A but not Project B, a list request returns only workflows from Project A.

This filtering does not produce error responses. If a list endpoint returns fewer results than expected, verify your role assignments in the target projects.

To request access, provide your platform administrator with your username or service account name, the target projects, and the required resource:action permissions.