Retrieve a role with its permissions

Beta

GET

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

GET

/api/v1/organisation/:orgId/role/:roleId

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

1 {
2   "id": 1,
3   "name": "Administrator",
4   "name_translation_key": "user_role_administrator_name",
5   "description": "Full access to all organization features and settings.",
6   "description_translation_key": "user_role_administrator_description",
7   "user_count": 4,
8   "type": "system",
9   "is_system_role": true,
10   "permissions": [
11     {
12       "id": 1,
13       "resource": "ApiCallback",
14       "action": "List"
15     },
16     {
17       "id": 2,
18       "resource": "Endpoint",
19       "action": "List"
20     },
21     {
22       "id": 3,
23       "resource": "Endpoint",
24       "action": "Create"
25     },
26     {
27       "id": 4,
28       "resource": "Endpoint",
29       "action": "Delete"
30     },
31     {
32       "id": 5,
33       "resource": "ServicePolicy",
34       "action": "List"
35     }
36   ]
37 }

Organisation.Role + Get

Roles: Administrator User

Returns a single role with its full permission list. Works for both system and custom roles.

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` + `Get` <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 a single role with its full permission list. Works for both system and custom roles. 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

roleIdintegerRequired>=1

Numeric identifier of the role.

orgIdinteger or enumRequired

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

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.

is_system_roleboolean

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

permissionslist of objectsOptional

Full list of permissions assigned to this role.

Errors

404

Not Found Error