Use the Roles API

Retrieve information about roles within the Account Manager system. Roles define permissions and access levels that can be assigned to Users and API Clients. Roles can be global (applying across all instances) or instance-specific (applying to particular instances). Each role has a set of permissions and can be assigned to either Users or API Clients, or both.

To retrieve a paginated list of all roles available in the system, send a GET request to /dw/rest/v1/roles. Use the pageable query parameter to control pagination. See the getRoles endpoint reference for complete details.

Use the roleTargetType query parameter to filter roles by whether they can be assigned to Users or API Clients:

  • ApiClient: Return only roles that can be assigned to API Clients
  • User: Return only roles that can be assigned to Users

If roleTargetType isn't specified, the response includes all roles regardless of target type.

To retrieve detailed information about a specific role, send a GET request to /dw/rest/v1/roles/{roleId}. See the getRole endpoint reference for complete details.

Each role includes these properties:

  • id: Unique identifier of the role.
  • description: Description of the role.
  • roleEnumName: Enumeration name of the role (used in role tenant filters).
  • permissions: List of permissions granted by this role.
  • scope: Scope level of the role (GLOBAL or INSTANCE).
  • targetType: Type of entity the role can be assigned to (ApiClient or User).
  • twoFAEnabled: Indicates if two-factor authentication is required for the role.

Managing permissions involves interacting with roles and role tenant filters. Note that these fields use different identifiers depending on the context.

  • When assigning roles to a User or API Client, reference the role by its ID.
  • When restricting access via roleTenantFilter, reference the role by its enum name.
    • The roleTenantFilter allows you to scope permissions to specific instances. It follows the format roleEnum:{tenant}. For example, BM_USER:abcd_prd.
    • You can specify multiple tenants for a single role using a comma-separated list: BM_USER:abcd_prd,dcba_prd.

Both the id and roleEnumName for a given role can be retrieved via the getRole endpoint.