[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 affects developers who:

  • Manage domain-level security and access control.
  • Build custom administration tools to automate role provisioning.
  • Monitor Audit Log API events and need to resolve role IDs into human-readable metadata.

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+

Field Documentation

Field Name Type Description
gid string The unique identifier for the role.
name string The user-facing name of the role.
description string A brief explanation of the role’s purpose.
is_standard_role boolean Whether the role is a system standard role or a custom-created role.

Examples

Get all roles

To retrieve a paginated list of roles within a workspace:

// GET /roles?workspace=12345&limit=50
{
  "data": [
    {
      "gid": "1234",
      "resource_type": "role",
      "name": "Project Creator",
      "description": "Can create projects within the organization.",
      "is_standard_role": true
    }
  ],
  "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/1234
{
  "data": {
    "gid": "1234",
    "resource_type": "role",
    "name": "Domain Admin",
    "description": "Full administrative access to the domain.",
    "is_standard_role": true
  }
}

Create a Custom Role

// POST /roles
{
  "data": {
    "workspace": "12345",
    "name": "Project Auditor",
    "description": "Read-only access to all projects for compliance reviews."
  }
}

Delete a Role

In this implementation, the DELETE endpoint only supports the deletion of roles that have no active user assignments. Developers must use SCIM or other assignment APIs to clear role memberships before calling this endpoint.

// 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