[ New ] Granular RBAC Permissions

English Forum Developers & API Changelog
1

Granular RBAC Permissions

This is the canonical thread for all RBAC permission additions to the RbacRole resource. As new permissions are introduced, they will be added here as dated entries. Subscribe to this topic to stay informed, and check the entries below for the latest additions.

Current entries:

  • Creation Permissions: create_project, create_goal, create_portfolio, create_read_only_link, share_teams_with_org
  • Visibility Permissions: view_shared_with_org_projects, view_public_teams, view_shared_with_org_tasks, view_shared_with_org_portfolios

This changelog covers permissions added to the permissions object on the RbacRole resource. These permissions are accessible through the existing RBAC Role API endpoints (GET, POST, PUT on /roles). No new endpoints are introduced by these permission additions.

Each entry below documents a set of related permissions, including field definitions, behavior notes, and examples. New entries will be appended as additional permissions are released.

Important behavior for all permissions

These notes apply to every permission documented in this thread.

Locked roles (Super Admin and Guest)

Super Admin and Guest roles have locked configurations. Attempting to modify a locked permission field via PUT /roles/{role_gid} on a Super Admin or Guest role returns a 403 Forbidden:

// PUT /roles/{role_gid}
{
  "errors": [
    {
      "error": "permission_restricted_for_role_type",
      "message": "some_permission can not be elevated for guest role type.",
      "user_message": "some_permission can not be elevated for guest role type.",
      "help": "For more information on API status codes and how to handle them, read the docs on errors: https://developers.asana.com/docs/errors"
    }
  ]
}

Enforcement errors when an action is denied

The error above is returned when you try to change a locked role’s permissions. Separately, when a user whose role lacks a given permission attempts the corresponding action, the action endpoint itself rejects the request. These enforcement errors use a different shape — see the Creation Permissions behavior notes for the specific error codes returned. Build graceful handling for both cases.

Rollout

Permissions are introduced gradually. A permission field appears in the API response and enforcement begins once it is available for a domain; it is documented as public in this thread only after it is fully released. No client-side opt-in or special request headers are required since the rollout is handled entirely on the backend.

Creation Permissions: create_project, create_goal, create_portfolio, create_read_only_link, share_teams_with_org

Available now.

Summary

These permissions extend RBAC to control which roles can create specific resource types and perform sharing actions. Admins can now restrict roles from creating projects, goals, or portfolios, generating read-only links, or sharing teams with the organization — providing tighter governance over how work and access structures are created within the domain.

Who is affected

Admins:

  • You can now toggle these creation and sharing permissions when creating or editing custom roles.
  • Before restricting creation permissions, consider whether users in the affected role need to create these resources as part of their workflows. Restricting create_project on a role assigned to active project managers, for example, would block their core workflow.
  • Check whether any integrations or apps in your domain create these resources on behalf of users assigned to the affected role.

App developers:

  • If your app creates projects, goals, portfolios, or read-only links on behalf of a user, the user’s role must include the corresponding creation permission. If the permission is not present, the API rejects the request.
  • Document which creation permissions your app requires, and surface clear messaging when a creation request fails due to insufficient role permissions.

Field documentation

Field Name Type Description
create_project boolean Controls whether a user with this role can create projects.
create_goal boolean Controls whether a user with this role can create goals.
create_portfolio boolean Controls whether a user with this role can create portfolios.
create_read_only_link boolean Controls whether a user with this role can generate read-only links for resources.
share_teams_with_org boolean Controls whether a user with this role can share a team with the organization (create a public team).

Behavior notes

  • No migration required. Existing roles retain their current behavior.
  • The same locked-role behavior applies: Super Admin and Guest role types have locked configurations for these fields, and attempting to modify them via PUT returns a 403 Forbidden with permission_restricted_for_role_type (see “Important behavior for all permissions” above).
  • Defaults by base role type: create_project and create_portfolio default to true for all base role types, including guest. create_goal, create_read_only_link, and share_teams_with_org default to true for member, admin, and super_admin, and false for guest.

Enforcement errors when a creation action is denied

When a user whose role lacks a creation permission attempts the corresponding action, the action endpoint returns a 403 Forbidden. The error code varies by resource:

Action Endpoint(s) Error code
Create project POST /projects, POST /workspaces/{workspace_gid}/projects, POST /teams/{team_gid}/projects, POST /projects/{project_gid}/duplicate write_access_failure
Create portfolio POST /portfolios write_access_failure
Create public team POST /teams (with "visibility": "public", or with no visibility passed, which defaults to public); PUT /teams/{team_gid} (setting "visibility": "public") team_admin_setting_blocks_editing_visibility
Create goal POST /goals goal_write_access_failure
Create read-only link Not accessible through the API —

Example — creating a project without create_project:

// POST /projects
{
  "errors": [
    {
      "error": "write_access_failure",
      "message": "You do not have permission to perform that action.",
      "user_message": "You do not have permission to perform that action.",
      "help": "For more information on API status codes and how to handle them, read the docs on errors: https://developers.asana.com/docs/errors"
    }
  ]
}

Example — creating a goal without create_goal:

// POST /goals
{
  "errors": [
    {
      "error": "goal_write_access_failure",
      "message": "You do not have permission to perform that action.",
      "user_message": "You don't have permission to perform that action. To gain permission, reach out to the goal's admin.",
      "help": "For more information on API status codes and how to handle them, read the docs on errors: https://developers.asana.com/docs/errors"
    }
  ]
}

Examples

Creating a role with restricted creation permissions:

// POST /roles
{
  "data": {
    "workspace": "67890",
    "name": "Limited Contributor",
    "description": "Can view and edit assigned work but cannot create new projects or goals",
    "base_role_type": "member",
    "permissions": {
      "create_project": false,
      "create_goal": false,
      "create_portfolio": false,
      "create_read_only_link": true,
      "share_teams_with_org": false
    }
  }
}

Visibility Permissions: view_shared_with_org_projects, view_public_teams, view_shared_with_org_tasks, view_shared_with_org_portfolios

Available now.

Summary

These permissions provide a middle ground between full organizational visibility and fully private resources. Admins can restrict specific roles — such as those assigned to contractors, temporary staff, or interns — so that users in those roles only see work they are directly assigned to, without requiring projects, teams, tasks, or portfolios to be made entirely private.

Who is affected

Admins:

  • You can now toggle these visibility permissions when creating or editing custom roles.
  • Before disabling these permissions for a role, verify whether any integrations or apps in your domain rely on users with that role being able to list org-shared projects, teams, tasks, or portfolios. Disabling visibility for a role also affects API calls made on behalf of users assigned to that role.

App developers:

  • If a user’s role does not include the relevant visibility permission, API calls made on behalf of that user will return fewer results when listing the corresponding resource type.
  • Build in graceful handling for cases where expected resources are not returned — for example, informative messaging or reduced-scope responses rather than silent failures.

Field documentation

Field Name Type Description
view_shared_with_org_projects boolean Controls whether a user with this role can view and join projects shared with the organization.
view_public_teams boolean Controls whether a user with this role can view and join public teams.
view_shared_with_org_tasks boolean Controls whether a user with this role can view tasks shared with the organization.
view_shared_with_org_portfolios boolean Controls whether a user with this role can view portfolios shared with the organization.

Behavior notes

  • No migration required. Existing roles retain their current behavior.
  • Only custom roles based on the member or admin base_role_type can have these permissions toggled. Super Admins always retain visibility; Guests are always blocked.
  • Defaults by base role type: all four default to true for member, admin, and super_admin, and false for guest.
  • The same locked-role behavior applies: modifying these fields on a Super Admin or Guest role via PUT returns 403 Forbidden with permission_restricted_for_role_type (see “Important behavior for all permissions” above).
  • Unlike the creation permissions, these do not reject an action with an error. When a role lacks a visibility permission, the affected resources are simply omitted from list responses made on behalf of that user.

Examples

Reading a role’s permissions:

// GET /roles/12345
{
  "data": {
    "gid": "12345",
    "resource_type": "role",
    "name": "Custom Member Role",
    "description": "A custom role with restricted visibility",
    "base_role_type": "member",
    "is_standard_role": false,
    "permissions": {
      "view_shared_with_org_projects": false,
      "view_public_teams": false,
      "view_shared_with_org_tasks": false,
      "view_shared_with_org_portfolios": false
    }
  }
}

Creating a role with restricted visibility:

// POST /roles
{
  "data": {
    "workspace": "67890",
    "name": "Restricted Member",
    "description": "Member role without org-wide visibility",
    "base_role_type": "member",
    "permissions": {
      "view_shared_with_org_projects": false,
      "view_public_teams": false,
      "view_shared_with_org_tasks": false,
      "view_shared_with_org_portfolios": false
    }
  }
}

Updating visibility permissions on an existing role:

// PUT /roles/12345
{
  "data": {
    "permissions": {
      "view_shared_with_org_projects": true,
      "view_public_teams": true,
      "view_shared_with_org_tasks": true,
      "view_shared_with_org_portfolios": true
    }
  }
}

Full permissions example

A role showing all permissions documented in this thread:

// GET /roles/12345
{
  "data": {
    "gid": "12345",
    "resource_type": "role",
    "name": "Full Member",
    "description": "Standard member with full creation and visibility permissions",
    "base_role_type": "member",
    "is_standard_role": false,
    "permissions": {
      "create_project": true,
      "create_goal": true,
      "create_portfolio": true,
      "create_read_only_link": true,
      "share_teams_with_org": true,
      "view_shared_with_org_projects": true,
      "view_public_teams": true,
      "view_shared_with_org_tasks": true,
      "view_shared_with_org_portfolios": true
    }
  }
}

Resources

Please let us know if you have questions! I’m here to help.

2 Likes