[New] RBAC Role API Endpoints (CRUD)

English Forum Developers & API Changelog
1

[New] RBAC Role API Endpoints (CRUD)

Summary

We are introducing a suite of API endpoints to support Role-Based Access Control (RBAC) roles. This update allows developers to programmatically create, retrieve, update, and delete standard and custom roles within a domain. These endpoints provide the necessary infrastructure to manage centralized permissions and resolve role IDs found in audit log events.

Who is affected

This change is relevant to developers who:

  • Build automation around domain-level role provisioning (e.g., syncing roles from an identity provider via SCIM alongside these endpoints).
  • Monitor Audit Log API events and need to resolve role GIDs into role names and descriptions.
  • Manage admin-level security and access control configuration programmatically.

Timeline

The endpoints are now live for all organizations.

Usage

New Endpoints

The following endpoints are now available for RBAC role management:

Endpoint Requirement Licensing
GET /roles Admin / Super Admin All Tiers
GET /roles/{role_gid} Admin / Super Admin All Tiers
POST /roles ā€œManage rolesā€ permission Enterprise+
PUT /roles/{role_gid} ā€œManage rolesā€ permission Enterprise+ (Enterprise for Guest Invites)
DELETE /roles/{role_gid} ā€œManage rolesā€ permission Enterprise+

OAuth scopes: Read operations require roles:read. Write operations (POST, PUT, DELETE) require roles:write. See OAuth scopes documentation for configuration details.

Field Reference

Response fields (returned by GET endpoints)

Field Type Description
gid string Globally unique identifier for the role.
resource_type string Always "role".
name string The user-facing name of the role.
description string A brief explanation of the roleā€™s purpose.
is_standard_role boolean true for system-defined standard roles, false for custom roles. Defaults to false when creating a new role.

Required body parameters for POST /roles

Field Type Required Description
workspace string Yes The GID of the workspace in which to create the role.
name string Yes The name for the new role.
description string Yes A description of the roleā€™s purpose.
base_role_type string Yes The base role type that this custom role extends. Determines the starting permission set for the role. See the Create a role reference for valid values.
permissions object Optional An object defining the specific permissions for this role. If omitted, the role inherits the default permissions from base_role_type. Asana may add new permissions in the future as new features are introduced. See the Permissions reference for available fields.

Examples

Get all roles

To retrieve a paginated list of roles within a workspace:

// GET /roles?workspace=12345&limit=50

{
  "data": [
    {
      "gid": "12345",
      "resource_type": "role",
      "name": "Developer",
      "description": "This role has exclusive access to create app and PAT tokens.",
      "is_standard_role": false
    }
  ],
  "next_page": {
    "offset": "eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9",
    "path": "/roles?limit=50&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9",
    "uri": "https://app.asana.com/api/1.0/roles?limit=50&offset=eyJ0eXAiOJiKV1iQLCJhbGciOiJIUzI1NiJ9"
  }
}

Get a specific role

To retrieve details for a single role ID:

// GET /roles/12345
{
  "data": {
    "gid": "12345",
    "resource_type": "role",
    "name": "Developer",
    "description": "This role has exclusive access to create app and PAT tokens.",
    "is_standard_role": false
  }
}

Create a Custom Role

// POST /roles

{
  "data": {
    "workspace": "12345",
    "name": "Project Auditor",
    "description": "Read-only access to all projects for compliance reviews.",
    "base_role_type": "member",
    "permissions": {
      "export_project_data": true,
      "upload_attachments": false,
      "create_team": false,
      "task_deletion_policy": "none",
      "create_app_authorization": false,
      "create_pat_authorization": false,
      "import_data": false,
      "allowed_guest_invites": "none"
    }
  }
}

In this example, the ā€œProject Auditorā€ role can export project data but cannot upload attachments, create teams, delete tasks, create app or PAT authorizations, import data, or invite guests. Any permission fields not included in the request will use the defaults inherited from the base_role_type.

Update a role

Update the name, description, or permissions of an existing custom role. You only need to include the fields you want to change:

// PUT /roles/5678

{
  "data": {
    "name": "Senior Project Auditor",
    "description": "Read-only access to all projects and portfolios for compliance reviews.",
    "permissions": {
      "export_project_data": true,
      "share_portfolios_with_org": true
    }
  }
}

Delete a Role

The DELETE endpoint only supports deleting roles that have no active user assignments. Attempting to delete a role with assigned users will return an error. Reassign or remove users from the role first ā€” this can be done via SCIM user provisioning.

// DELETE /roles/1234

{
  "data": {}
}

Why weā€™re making this change

As organizations scale, managing permissions manually through the Admin Console becomes complex. By exposing CRUD functionality for RBAC roles, we are enabling administrators to automate role management via the API.

Resources

3 Likes