Create a new role. Then optionally add scopes by using the Update Role Scopes API. No scopes are added by default.

Creates a new custom RBAC role for the tenant with a specified name and description.

Use this endpoint to define a new role as part of setting up fine-grained access control — then assign scopes to it via PUT /authz2/v1/roles/{role_id}/scopes before assigning it to users.

About Create Role

Custom roles in Esper allow Enterprise Admins(and other users with certain permissions) to define permission sets that are more granular than the built-in fixed roles. A newly created role has no scopes by default — it must be populated with the desired action permissions via PUT /authz2/v1/roles/{role_id}/scopes before it grants any meaningful access. Once scoped, the role can be assigned to users by setting their role to AuthZ Role User and providing the role's UUID as authz_role_id via PUT /authz2/v1/users/{user_id}.

Key Fields / Request Body

name — the display name for the new role

description — a human-readable description of the role's intended purpose and scope of access

Key Fields (Response)

id — the UUID of the newly created role; store this immediately for use in scope assignment and user assignment calls

name — the name as set in the request

description — the description as set in the request

role_type — integer indicating the type of role

Common Use Cases

Creating a read-only role for auditors that grants only read:device and read:group scopes

Defining a role for field technicians with a limited set of device command permissions

Building a role hierarchy for multi-team fleet management

Best Practices

Always follow role creation immediately with PUT /authz2/v1/roles/{role_id}/scopes — a role with no scopes assigned will not grant users any access Use clear, descriptive name and description values that reflect the intended job function, not the technical scope list, to keep the role list auditable Store the returned id before making any further calls — it is required for scope assignment and cannot be retrieved from this response again without calling GET /authz2/v1/roles/

Workflow

POST to this endpoint with a name and description for the new role

Store the returned role id

Call PUT /authz2/v1/roles/{role_id}/scopes to assign the desired permission scopes to the role

Assign the role to users via PUT /authz2/v1/users/{user_id} with role: AuthZ Role User and the role UUID as authz_role_id