Endpoints
List roles
List roles with their permissions and the count of Users on each, system roles first. The caller sees system roles and their own Org's custom roles, with super-admin roles hidden; a super-admin sees the roles of every Org. Requires `users:read`.
GET /v1/roles/list_roles
Request examples
Set MYREMOTELY_BASE_URL to the environment you intend to call.
curl --fail-with-body \
--header "x-api-key: $MYREMOTELY_API_KEY" \
"$MYREMOTELY_BASE_URL/v1/roles/list_roles"const baseUrl = process.env.MYREMOTELY_BASE_URL
const apiKey = process.env.MYREMOTELY_API_KEY
if (!baseUrl || !apiKey) throw new Error('API base URL and key are required')
const response = await fetch(`${baseUrl}/v1/roles/list_roles`, {
method: 'GET',
headers: { 'x-api-key': apiKey },
})
if (!response.ok) throw new Error(`Request failed: ${response.status}`)
const data = await response.json()Responses
200 Success
application/json
| Field | Type | Required | Description |
|---|---|---|---|
data | array | Yes | — |
{
"data": [
{
"id": "string",
"name": "string",
"displayName": "string",
"description": "string",
"isSystem": "string",
"isSuperAdmin": "string",
"orgId": "string",
"createdAt": "string",
"updatedAt": "string",
"permissions": "string",
"_count": "string"
}
]
}401 The API key is missing, invalid, expired, or revoked.
application/problem+json
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | A stable documentation URI for this problem. |
title | string | Yes | A short problem title. |
detail | string | Yes | A safe explanation of this occurrence. |
code | string | Yes | A stable machine-readable problem code. |
requestId | string | Yes | The request ID to include when contacting MyRemotely support. |
status | number | Yes | The HTTP status code. |
{
"type": "https://app.myremotely.ai/en/docs/errors#invalid-api-key",
"title": "Unauthorized",
"status": 401,
"detail": "Provide a valid API key.",
"code": "invalid_api_key",
"requestId": "request_demo_01"
}403 The API key does not have the users:read scope.
application/problem+json
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | A stable documentation URI for this problem. |
title | string | Yes | A short problem title. |
detail | string | Yes | A safe explanation of this occurrence. |
code | string | Yes | A stable machine-readable problem code. |
requestId | string | Yes | The request ID to include when contacting MyRemotely support. |
status | number | Yes | The HTTP status code. |
{
"type": "https://app.myremotely.ai/en/docs/errors#missing-scope",
"title": "Forbidden",
"status": 403,
"detail": "The users:read scope is required.",
"code": "missing_scope",
"requestId": "request_demo_01"
}429 The API key request budget is exhausted.
application/problem+json
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | A stable documentation URI for this problem. |
title | string | Yes | A short problem title. |
detail | string | Yes | A safe explanation of this occurrence. |
code | string | Yes | A stable machine-readable problem code. |
requestId | string | Yes | The request ID to include when contacting MyRemotely support. |
status | number | Yes | The HTTP status code. |
{
"type": "https://app.myremotely.ai/en/docs/errors#rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "Try the request again later.",
"code": "rate_limited",
"requestId": "request_demo_01"
}500 MyRemotely could not complete the request.
application/problem+json
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | A stable documentation URI for this problem. |
title | string | Yes | A short problem title. |
detail | string | Yes | A safe explanation of this occurrence. |
code | string | Yes | A stable machine-readable problem code. |
requestId | string | Yes | The request ID to include when contacting MyRemotely support. |
status | number | Yes | The HTTP status code. |
{
"type": "https://app.myremotely.ai/en/docs/errors#internal-error",
"title": "Internal error",
"status": 500,
"detail": "The request could not be completed.",
"code": "internal_error",
"requestId": "request_demo_01"
}Last updated Oct 3, 2026