List roles
Returns a list of all roles accessible to the authenticated user, ordered by name.
Roles define which channels (door controllers) people or groups have access to, optionally within specific time shifts.
This endpoint does not support pagination.
/api/3/roles
Authentication
This endpoint requires authentication:
Use an OAuth 2.0 access token in the Authorization header. This is the recommended authentication method for all integrations. OAuth provides automatic token expiration, granular permission scopes, detailed usage tracking, and per-integration revocation. Learn how to obtain an access token.
Header Format:
Authorization: Bearer YOUR_ACCESS_TOKEN
Required Scopes:
account.role.readonly
Responses
List of roles retrieved successfully
Response Fields
id
integer
required
Unique identifier for the role
eg. 42
name
string
required
Name of the role (must be unique within the account)
eg. Office Staff
shift_id
integer | null
ID of the shift defining when this role grants access (null means 24/7 access)
eg. 10
notes
string | null
Additional notes about this role
eg. Access to main building during business hours
created_at
string
required
Timestamp of creation
updated_at
string
required
Timestamp of last update
Unauthorized - Invalid or missing authentication
Response Fields
error
string
eg. unauthorized
error_description
string
eg. The access token is invalid
Forbidden - User does not have permission
Response Fields
error
string
eg. forbidden
error_description
string
eg. You are not authorized to access this resource
Internal Server Error
Response Fields
error
string
eg. internal_server_error
error_description
string
eg. An unexpected error occurred
Mentioned in Guides
This endpoint is used in the following guides: