API v1 Reference › Roles

Creates a workspace role.

POSThttps://api.awork.com/api/v1/roles
POST https://api.awork.com/api/v1/roles

Creates a workspace role. The role starts with the submitted settings.

Authentication

AuthorizationBearer

Send your token in the Authorization: Bearer <token> header. See Authentication for API keys and OAuth.

Request body Required

The role form payload.

application/json

namestringRequired
minLength: 1

The name of the role. Must be unique.

isAdminRolebooleanOptional

Whether this is the admin role. Only one role can be the admin role.

isGuestRolebooleanOptional

Whether this is the guest role. Only one role can be the guest role.

Responses

200 OK

application/json

namestringRequired
minLength: 1

The name of the role. Must be unique.

isAdminRolebooleanOptional

Whether this is the admin role. Only one role can be the admin role.

isGuestRolebooleanOptional

Whether this is the guest role. Only one role can be the guest role.

idstringOptional
format: uuid

The id of the role.

isAgentRolebooleanOptional

Whether this is a retained role from the legacy agent-as-user model. The role cannot be modified.

isPresetbooleanOptional

Whether this role is one of the preset roles. Preset roles can be edited, archived and deleted.

isArchivedbooleanOptional

Whether the role has been archived.

createdBystringOptional
format: uuid

The id of the user who created this role.

createdOnstringOptional
format: date-time

The date this role was created.

updatedBystringOptional
format: uuid

The id of the user who updated this role.

updatedOnstringOptional
format: date-time

The date this role was last modified.

400 Bad Request

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

Search documentation