List system and custom roles

Beta

GET

https://cdn.emnify.net/api/v1/organisation/:orgId/role

GET

/api/v1/organisation/:orgId/role

curl https://cdn.emnify.net/api/v1/organisation/my/role \
     -H "Authorization: Bearer <token>"

[
  {
    "id": 1,
    "name": "Administrator",
    "name_translation_key": "user_role_administrator_name",
    "description": "Full access to all organization features and settings.",
    "description_translation_key": "user_role_administrator_description",
    "user_count": 4,
    "type": "system",
    "is_system_role": true
  },
  {
    "id": 2,
    "name": "User",
    "name_translation_key": "user_role_user_name",
    "description": "Partial write access.",
    "description_translation_key": "user_role_user_description",
    "user_count": 12,
    "type": "system",
    "is_system_role": true
  },
  {
    "id": 3,
    "name": "Observer",
    "name_translation_key": "user_role_observer_name",
    "description": "Read-only access.",
    "description_translation_key": "user_role_observer_description",
    "user_count": 3,
    "type": "system",
    "is_system_role": true
  },
  {
    "id": 101,
    "name": "Fleet operator",
    "name_translation_key": null,
    "description": "Can manage endpoints and SIMs but not billing.",
    "description_translation_key": null,
    "user_count": 2,
    "type": "custom",
    "is_system_role": false
  }
]

Organisation.Role + List

Roles: Administrator User

Returns all roles in the Workspace. System roles come first, in the order Administrator, User, and Observer, followed by custom roles alphabetically.

Pass include_permissions=true to also receive each role’s permission list. Use my in place of a numeric orgId to target the caller’s own Workspace.

<Info icon="fa-light fa-lock" className="permission-callout"> <div className="permission-callout__header"><span className="permission-callout__title"><span className="permission-callout__label">Required permissions</span> <span className="fern-docs-badge small blue subtle rounded-full permission-callout__beta">Beta</span></span> <span className="permission-callout__learn-more">[Learn more](/developers/api-guidelines/permissions#how-permissions-work)</span></div> `Organisation.Role` + `List` <div className="permission-callout__roles"><span className="permission-callout__roles-label">Roles:</span> <Badge intent="info">Administrator</Badge> <Badge intent="info">User</Badge></div> </Info> Returns all roles in the Workspace. System roles come first, in the order Administrator, User, and Observer, followed by custom roles alphabetically. Pass `include_permissions=true` to also receive each role's permission list. Use `my` in place of a numeric `orgId` to target the caller's own Workspace.

Authentication

AuthorizationBearer

An auth_token should be provided to authenticate a session.

To obtain an auth_token, see the /api/v1/authenticate POST request.

Path parameters

orgIdinteger or enumRequired

Workspace identifier. Either a positive integer organization ID, or the literal string my to target the caller’s own Workspace.

Query parameters

include_permissionsbooleanOptionalDefaults to false

When true, each returned role also includes its permissions array. Defaults to false to keep the list response light.

Response

Successful response.

iddouble

Unique role identifier.

namestring

Display name of the role.

name_translation_keystring or null

Translation key for the role name. Set for system roles only.

descriptionstring

Human-readable description of the role. An empty string when no description has been set.

description_translation_keystring or null

Translation key for the role description. Set for system roles only.

user_countdouble

Number of users assigned to this role in the Workspace.

typeenum

Whether this is a system-defined role or an organization’s custom role.

Allowed values:

is_system_roleboolean

True for built-in system roles, which can’t be modified or deleted.

permissionslist of objectsOptional

Permissions assigned to this role. Present only on single-role retrieval, or on the list when include_permissions=true.

Errors

404

Not Found Error