Create a custom role

Beta

POST

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

POST

/api/v1/organisation/:orgId/role

$ curl -X POST https://cdn.emnify.net/api/v1/organisation/orgId/role \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "name": "Procurement",
>   "description": "Orders SIMs and registers them into the Workspace. No device operations, reports, or billing.",
>   "permissions": [
>     {
>       "resource": "Sim",
>       "action": "List"
>     },
>     {
>       "resource": "Sim.Event",
>       "action": "List"
>     },
>     {
>       "resource": "Event.Type",
>       "action": "List"
>     },
>     {
>       "resource": "Operator",
>       "action": "List"
>     },
>     {
>       "resource": "SimBatch.Bic",
>       "action": "Get"
>     },
>     {
>       "resource": "SimBatch.Bic",
>       "action": "Add"
>     },
>     {
>       "resource": "Endpoint",
>       "action": "Create"
>     },
>     {
>       "resource": "Organisation.Billing.Settings",
>       "action": "Get"
>     },
>     {
>       "resource": "TariffProfile",
>       "action": "List"
>     },
>     {
>       "resource": "ServiceProfile",
>       "action": "List"
>     },
>     {
>       "resource": "IpAddressSpace",
>       "action": "List"
>     },
>     {
>       "resource": "Tag",
>       "action": "List"
>     },
>     {
>       "resource": "Shop.Order",
>       "action": "Create"
>     },
>     {
>       "resource": "Shop.Order.Calculation",
>       "action": "Get"
>     },
>     {
>       "resource": "Shop.Product",
>       "action": "List"
>     },
>     {
>       "resource": "PaymentOption",
>       "action": "List"
>     },
>     {
>       "resource": "ShippingOption.Country",
>       "action": "List"
>     },
>     {
>       "resource": "Organisation.Contact",
>       "action": "List"
>     },
>     {
>       "resource": "Shop.Order",
>       "action": "List"
>     },
>     {
>       "resource": "Shop.Order.Invoice",
>       "action": "Get"
>     },
>     {
>       "resource": "Shop.Order.Item.Artifact",
>       "action": "Get"
>     }
>   ]
> }'

1 {
2   "id": 102,
3   "name": "Procurement",
4   "name_translation_key": null,
5   "description": "Orders SIMs and registers them into the Workspace. No device operations, reports, or billing.",
6   "description_translation_key": null,
7   "user_count": 0,
8   "type": "custom",
9   "is_system_role": false
10 }

Organisation.Role + Create

Roles: Administrator

Creates a custom role in the Workspace. A Workspace can hold at most 50 custom roles, and the name must be unique within the Workspace.

Supply permissions either as permission_ids, using numeric IDs, or as permissions, using resource and action pairs, but not both. Retrieve the valid permissions with GET /api/v1/organisation/{orgId}/permission.

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` + `Create` <div className="permission-callout__roles"><span className="permission-callout__roles-label">Roles:</span> <Badge intent="info">Administrator</Badge></div> </Info> Creates a custom role in the Workspace. A Workspace can hold at most 50 custom roles, and the name must be unique within the Workspace. Supply permissions either as `permission_ids`, using numeric IDs, or as `permissions`, using resource and action pairs, but not both. Retrieve the valid permissions with `GET /api/v1/organisation/{orgId}/permission`. 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.

Request

This endpoint expects an object.

namestringRequiredformat: "^[A-Za-z0-9 _\-&']+$"2-50 characters

Unique role name within the Workspace. Use letters, digits, spaces, dashes, underscores, ampersands, and apostrophes. Leading and trailing whitespace is trimmed before validation and storage.

descriptionstring or nullOptional2-250 characters

Optional free-text description of the role. Omit it or pass null to store an empty string. When provided, it must be 2 to 250 characters. Leading and trailing whitespace is trimmed before validation and storage.

permission_idslist of doublesOptionalDefaults to []

IDs of permissions to assign. May be empty, and mutually exclusive with permissions. Deprecated or deleted permissions are rejected. Omit the field to send no value, because an explicit null is rejected.

permissionslist of objectsOptional

Resource and action pairs of permissions to assign, resolved to permission IDs on the server. Mutually exclusive with permission_ids. Deprecated or deleted permissions are rejected. Omit the field to send no value, because an explicit null is rejected.

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

400

Bad Request Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error