Sample - Asana API
POST/roles

Create a role

Creates a new RBAC role in the workspace. Supply the required role details and request the roles:write scope; use opt_fields to include additional properties in the response.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 1 body field
opt_fieldsarray<string>optional
Comma-separated list of response properties to include, including nested properties such as `permissions.assign_roles`; omit it to use the default response fields.

The role to create, including its name, description, base role type, and workspace.

dataobjectoptional
Role creation data containing the required role properties.

6 status codes
201Returns the newly created role object.
dataobjectoptional
400Returned when required role data is missing or a parameter is malformed.
errorsarray<object>optional
401Returned when the request does not include a valid authentication token.
errorsarray<object>optional
403Returned when the authenticated user does not have permission to create roles in the workspace.
errorsarray<object>optional
404Returned when the request action or referenced workspace does not exist.
errorsarray<object>optional
500Returned when a server-side problem prevents the role from being created.
errorsarray<object>optional

Error handling

The request requires the roles:write scope and must include name, description, base_role_type, and workspace. A 400 is returned for missing or malformed role data, a 401 when no valid authentication token is provided, and a 403 when the authenticated user lacks access. A 404 indicates that the referenced workspace or action does not exist; 500 indicates a server-side failure.