Assign RBAC roles to a service account

You can assign RBAC roles to a service account to control exactly which API actions it is authorized to perform.

Before you begin

  • A service account exists in the target project. For more information, see Create a service account.
  • You have the project administrator role in the project, or you have the role-assignment:assign permission.
  • You know the name of the role you want to assign. For a list of available roles, query the roles API or consult your automation orchestrator administrator.

About this task

Service accounts receive direct role assignments only. Unlike human users, service accounts cannot be members of groups.

By default, a newly created service account has no permissions. You must explicitly assign roles to grant the service account access to specific resources and actions.

Roles can be project-scoped or global. The scope determines where the service account's permissions apply:

  • Project-scoped roles grant permissions within a specific project only. Most service account use cases require project-scoped roles, because service accounts typically interact with resources in a single project.
  • Global roles grant permissions across the entire platform. Assign global roles only when the service account must access resources across multiple projects or perform platform-level operations.

Follow the principle of least privilege: assign only the roles that the service account needs to perform its intended function.

Procedure

  1. Identify the role that matches the permissions the service account needs.

    For example, if the service account must trigger workflow executions, identify a role that includes the execution:run permission.

  2. Send a POST request to the role assignments endpoint.

    Replace the placeholder values with the appropriate UUIDs and role name:

    $ curl -X POST \
    -H "Authorization: Bearer access_token" \
    -H "Content-Type: application/json" \
    -d '{
      "principal_id": "service_account_id",
      "role_name": "role_name",
      "project_id": "project_id"
    }' \
    https://orchestrator_host/api/v1/role_assignments

    Where:

    • access_token is your personal access token or session token.
    • service_account_id is the UUID of the service account.
    • role_name is the name of the role to assign, for example workflow-executor.
    • project_id is the UUID of the project to scope the assignment to. Omit this field for a global role assignment.
    • orchestrator_host is the hostname of your automation orchestrator instance.
    Note

    To assign a global role instead of a project-scoped role, omit the project_id field from the request body. Global roles grant platform-wide permissions and are not restricted to a single project.
  3. Verify the role assignment by listing role assignments for the service account: 
    $ curl -H "Authorization: Bearer access_token" \
    "https://orchestrator_host/api/v1/role_assignments?principal_id=service_account_id"

    The response includes the new role assignment with the role name, project scope, and creation timestamp.