The create role operation will create a new role with the specified request body.
Request
Request URI
| Method | Request URI |
|---|---|
| POST | https://{company-name}.helloid.com/api/v1/roles/ |
Request parameters
| Parameter | Description |
|---|---|
| {company-name} | The company name of the target company |
Request headers
| Header | Description |
|---|---|
| Content-Type | Required. Must be set to application/json. |
Sample request body
{
"name": "MyRole",
"Description": "Just a description",
"IsEnabled": true,
"IsDefault": true,
"UserNames": ["1aaa","A.Adair"],
"UserGuids": ["3216f4b1-c290-4b6f-8ddb-921889331f56","02cab5e8-3355-4558-98bc-5504aedab679"],
"GroupGuids": ["0422b39f-dc8d-4186-ad80-ffb00a9ca3b1", "cc7fcc99-e33d-41c6-b881-93aba98204c4", "4ab478c8-ffce-4ee1-a8d6-edd12f9d1668"],
"Rights": [65537, 131079]
}
Request body parameters
| Parameter | Description | Required/Optional | Default value |
|---|---|---|---|
| {Name} | The name of the role. | Required | - |
| {Description} | A description of the role. | Required | - |
| {IsEnabled} | Is the role enabled or disabled. | Optional | false |
| {IsDefault} | Is the role default. Default roles are linked to users when they are created. | Optional | false |
| {UserNames} | List of usernames to link to the role. | Optional | - |
| {UserGuids} | list of user Guids to link to the role. | Optional | - |
| {Rights} | List of right descriptors | Optional | - |
Right Descriptors
A right descriptor is a 32-bit number. The higher 16 bits are for object type, numbers starting from 1. The lower 16 bits are a bitmask, one bit for every right. The meaning of the bits depends on the object type. See the Role edit screen in the portal for the available rights. The available object types are listed below.
| Number | Object Type |
|---|---|
| 1 | Dashboard |
| 1 | Users |
| 3 | Applications |
| 4 | Groups |
| 5 | Roles |
| 6 | SMS Providers |
| 7 | Certificates |
| 8 | AD Connectors |
| 9 | Identity Providers |
| 10 | Reporting |
| 11 | Settings |
| 12 | Login Access Rules |
| 13 | Application Access Rules |
| 14 | Integrations |
| 15 | API Access |
| 16 | SMS Configurations |
| 17 | Admin Dashboard |
Response
Response status
| Code | Description |
|---|---|
| 200(OK) | Indicates that the operation was successful and the resource is created. |
| 400(BAD REQUEST) | Indicates that the operation was not successful. There were validation errors or the request body was malformed.If there were validation errors, the response will include a error result. |
| 401(UNAUTHORIZED) | Indicates that no authentication header was given or the api key and secret were invalid. If the api key and secret were valid check the configuration in your portal, it is possibilty these were IP restricted or are disabled. |
Please also see error result.
Please also see common HTTP status codes.
Sample response body
{
"roleGUID": "a53b3e24-e03a-4799-a911-96c4f396acaf",
"name": "MyRole",
"description": "Just a description",
"isSystem": false,
"isEnabled": true,
"isDefault": true,
"rights": [
65537,
131079
],
"users": [
"02cab5e8-3355-4558-98bc-5504aedab679",
"effce7dd-8901-49ca-95e0-8083c37a0801",
"3216f4b1-c290-4b6f-8ddb-921889331f56",
"4c58679d-ab2a-49bb-8be8-ffe1962ef8df"
],
"groups": [
"0422b39f-dc8d-4186-ad80-ffb00a9ca3b1",
"cc7fcc99-e33d-41c6-b881-93aba98204c4",
"4ab478c8-ffce-4ee1-a8d6-edd12f9d1668"
]
}
Example request with cURL
Replace placeholder values surrounded by { } with the actual values.
curl -u {api-key}:{api-secret} -X POST https://{company-name}.helloid.com/api/v1/users/
-H "Content-Type:application/json" -d
"{
"roleGUID": "a53b3e24-e03a-4799-a911-96c4f396acaf",
"name": "MyRole",
"description": "Just a description",
"isSystem": false,
"isEnabled": true,
"isDefault": true,
"rights": [
65537,
131079
],
"users": [
"02cab5e8-3355-4558-98bc-5504aedab679",
"effce7dd-8901-49ca-95e0-8083c37a0801",
"3216f4b1-c290-4b6f-8ddb-921889331f56",
"4c58679d-ab2a-49bb-8be8-ffe1962ef8df"
],
"groups": [
"0422b39f-dc8d-4186-ad80-ffb00a9ca3b1",
"cc7fcc99-e33d-41c6-b881-93aba98204c4",
"4ab478c8-ffce-4ee1-a8d6-edd12f9d1668"
]
}"