Roles

📘
Accessing RBAC role API endpoints
Access to these endpoints is governed by both user permissions and organization licensing tiers:

Read Access (GET): Available to users with Admin or Super Admin privileges.

Write Access (POST, PUT, DELETE): Requires the authenticated user to have the specific RBAC permission "Manage roles".

Licensing: Creating and managing custom roles requires the Enterprise+ tier. Editing guest invites in standard roles is available to both Enterprise and Enterprise+ tiers.

Asana’s Roles API allows you to programmatically manage Role-Based Access Control (RBAC) at the domain level. This provides a centralized way to define permissions and ensures that security teams can resolve role IDs found in audit log events to human-readable metadata.

Organizations use these endpoints to:

Automate Provisioning: Programmatically create and update custom roles to match internal security policies.
Enhance Auditing: Resolve role identifiers in the Audit Log API to understand exactly which permissions are associated with an event.
Scale Governance: Manage complex permission structures across large organizations without manual overhead in the Admin Console.

🚧
Important Notes

Deletion Logic: The DELETE endpoint follows an "Empty role" policy. A role can only be deleted if it has no active user assignments.

Standard vs. Custom: While standard roles (e.g., Admin, Member) can be retrieved, certain fields on standard roles are immutable. Only custom roles support full CRUD operations.

RbacRoleCompact

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`name`	string	The name of the role.
`description`	string	The description of the role.
`is_standard_role`	boolean	Whether the role is a standard role or a custom role. Defaults to `false`.

Example JSON for RbacRoleCompact:

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

RbacRole

Property	Type	Description
`gid`	string	Globally unique identifier of the resource, as a string.
`resource_type`	string	The base type of this resource.
`name`	string	The name of the role.
`description`	string	The description of the role.
`is_standard_role`	boolean	Whether the role is a standard role or a custom role. Defaults to `false`.
`creation_time`	string (date-time)	The time at which this role was created.
`modified_at`	string (date-time)	The time at which this role was last modified.
`base_role_type`	string	The base role type of the role. Click to show all enum values `admin` `guest` `member` `super_admin`
`permissions`	object	The permissions of the role.
`permissions.create_app_authorization`	boolean	Controls whether users with this role can create app authorizations
`permissions.create_pat_authorization`	boolean	Controls whether users with this role can create PAT authorizations
`permissions.share_goal_with_domain`	boolean	Controls whether users with this role can create company-wide goals
`permissions.share_portfolios_with_org`	boolean	Controls whether users with this role can create portfolios that are shared with the organization and share existing portfolios to the organization
`permissions.assign_roles`	boolean	Controls whether users with this role can assign guest, member, and admin roles to other users
`permissions.manage_roles`	boolean	Controls whether users with this role can create, edit, and delete roles
`permissions.export_project_data`	boolean	Controls whether users with this role can export project data
`permissions.task_deletion_policy`	string	Determines what tasks users with this role are allowed to delete Click to show all enum values `all` `none` `owned`
`permissions.download_mobile_attachments`	boolean	Controls whether users with this role can download attachments from mobile app
`permissions.import_data`	boolean	Controls whether users with this role can import data into the domain
`permissions.create_global_custom_fields`	boolean	Controls whether users with this role can create global custom fields
`permissions.upload_attachments`	boolean	Controls whether users with this role can upload attachments
`permissions.create_team`	boolean	Controls whether users with this role can create teams
`permissions.allowed_guest_invites`	string	Controls what type of email users with this role are allowed to invite Click to show all enum values `all` `none`
`permissions.create_and_edit_ai_automations`	boolean	Controls whether users with this role can create and edit AI automations
`permissions.proactive_ai`	boolean	Controls whether users with this role can use proactive AI features
`permissions.standard_ai`	boolean	Controls whether users with this role can use standard AI features
`permissions.create_and_edit_ai_teammates`	boolean	Controls whether users with this role can create and edit AI teammates
`permissions.share_teams_with_org`	boolean	Controls whether users with this role can share teams with the organization
`permissions.create_goal`	boolean	Controls whether users with this role can create goals
`permissions.create_project`	boolean	Controls whether users with this role can create projects
`permissions.create_read_only_link`	boolean	Controls whether users with this role can create read-only links
`permissions.create_portfolio`	boolean	Controls whether users with this role can create portfolios
`permissions.view_public_teams`	boolean	Controls whether users with this role can view public teams
`permissions.view_shared_with_org_projects`	boolean	Controls whether users with this role can view projects shared with the organization
`permissions.view_shared_with_org_tasks`	boolean	Controls whether users with this role can view tasks shared with the organization
`permissions.view_shared_with_org_portfolios`	boolean	Controls whether users with this role can view portfolios shared with the organization
`workspace`	object	Create-only. The workspace this role is associated with. Once created, roles cannot be moved to a different workspace. This attribute can only be specified at creation time.
`workspace.gid`	string	Globally unique identifier of the resource, as a string.
`workspace.resource_type`	string	The base type of this resource.
`workspace.name`	string	The name of the workspace.

Example JSON for RbacRole:

{
  "gid": "12345",
  "resource_type": "role",
  "name": "Developer",
  "description": "This role has exclusive access to create app and PAT tokens.",
  "is_standard_role": false,
  "creation_time": "2012-02-22T02:06:58.147Z",
  "modified_at": "2012-02-22T02:06:58.147Z",
  "base_role_type": "example string",
  "permissions": {
    "create_app_authorization": true,
    "create_pat_authorization": true,
    "share_goal_with_domain": true,
    "share_portfolios_with_org": true,
    "assign_roles": true,
    "manage_roles": true,
    "export_project_data": true,
    "task_deletion_policy": "all",
    "download_mobile_attachments": true,
    "import_data": true,
    "create_global_custom_fields": true,
    "upload_attachments": true,
    "create_team": true,
    "allowed_guest_invites": "all",
    "create_and_edit_ai_automations": true,
    "proactive_ai": true,
    "standard_ai": true,
    "create_and_edit_ai_teammates": true,
    "share_teams_with_org": true,
    "create_goal": true,
    "create_project": true,
    "create_read_only_link": true,
    "create_portfolio": true,
    "view_public_teams": true,
    "view_shared_with_org_projects": true,
    "view_shared_with_org_tasks": true,
    "view_shared_with_org_portfolios": true
  },
  "workspace": {
    "gid": "12345",
    "resource_type": "workspace",
    "name": "My Company Workspace"
  }
}