Skip to main content

POST - Create Role

POST/api/public/roles

Create a role

Defines a new role inside your TechWriter workspace. Provide a display name and an array of numeric privileges describing what users assigned to this role can do — for example, edit templates, manage users, or download published articles.

The privileges array accepts integer IDs only. Use the mapping below to translate each capability into its corresponding numeric value.

Request headers

HeaderValueRequiredDescription
AuthorizationBearer {YOUR_BEARER_TOKEN}requiredAccess token used to authenticate the API request.
Accept*/*optionalIndicates the response formats the client can accept.
Content-Typeapplication/jsonrequiredBody format for the create-role request.

Request body

Send a JSON object containing the role definition.

namestringrequiredDisplay name shown across the Administration → Roles screen.
privilegesinteger[]requiredList of privilege IDs assigned to the role. Must contain at least one value. Example: [3, 11, 16].

Privilege ID reference

Translate privilege names to the numeric IDs that the privileges array expects.

CategoryPrivilegeIDDescription
CommonArticles: Author Drafts0Create new articles, edit drafts, and submit them for review.
CommonArticles: Sign with Notary31Mark publications as notarized when the workspace has e-notarization enabled.
VisibilityWorkspace: Read All Content1Workspace-wide read access. Cannot modify resources unless paired with another privilege.
TemplatesTemplates: Use2Start a new article from a published template.
TemplatesTemplates: Author3Create and edit reusable templates.
TemplatesTemplates: Remove4Delete templates from the library.
TemplatesTemplates: Share5Share templates with other groups in the workspace.
TemplatesFolders: Author6Create and rename template folders.
TemplatesFolders: Remove7Delete template folders.
TemplatesFolders: Share8Share template folders with other groups.
Bulk PublishingBulk: View9View bulk publication runs and their progress.
Bulk PublishingBulk: Run10Start, edit, and download CSV exports for bulk publication runs.
Bulk PublishingBulk: Delete33Delete a bulk publication run.
AdministrationUsers: View11Open the Administration → Users page.
AdministrationUsers: Author12Invite new users and edit their profiles.
AdministrationUsers: Remove13Deactivate or delete user profiles.
AdministrationUsers: Assign Roles14Grant or revoke roles for users.
AdministrationUsers: Assign Groups15Add users to groups or remove them.
AdministrationRoles: Manage16View, create, and edit workspace roles.
AdministrationGroups: Manage17View, create, and edit user groups.
AdministrationBranding: Manage18Edit workspace styles, logos, and theming.
AdministrationNotifications: Manage19Open and edit notification templates.
AdministrationIntegrations: API Keys20Create, edit, and revoke external API integrations.
AdministrationIntegrations: Auth21Manage authorization templates for SSO and OAuth.
AdministrationIntegrations: Certificates22Manage client certificates used by integrations.
AdministrationSettings: Manage32Edit workspace-wide settings.
AdministrationConfirmation Pages: Manage34Manage post-publication thank-you and confirmation pages.
ArticlesArticle: Reinstate23Restore an article that was previously cancelled.
ArticlesArticle: Reassign to Self24Reassign an in-review article to yourself before approving it.
ArticlesArticle: Resend25Resend articles waiting for reviewer signature.
ArticlesArticle: Delegate26Delegate review of an in-flight article to another reviewer.
ArticlesArticle: Cancel27Cancel articles that are still in Draft or Out-of-Review.
DownloadsDownload: Final Article28Download the final published article file.
DownloadsDownload: Audit Trail29Download the audit trail for eligible articles.
DownloadsDownload: Output Bundle30Download the advanced output bundle for an article.
OtherArticle: Return to Draft35Send an article back to Draft state.
OtherEditor Delegation36Manage editor delegation rules across the workspace.
OtherReviewer Groups: Manage37Create and edit reviewer groups.
OtherArticles: Export38Bulk export articles when the export module is enabled.

Response codes

The API uses conventional HTTP status codes. 2xx indicate success, 4xx indicate client errors, and 5xx indicate server-side issues.

201 CreatedRole was created successfully. The response includes the new role identifier.
400 Bad RequestThe payload is malformed: missing name, empty privileges, or non-numeric IDs.
401 UnauthorizedAuthentication failed: missing, invalid, or expired bearer token.
403 ForbiddenThe token is valid but lacks the roles:write scope.
409 ConflictA role with the same name already exists in the workspace.
422 UnprocessableOne or more privilege IDs are not recognized by the platform.
429 Too ManyYou exceeded the rate limit. Retry after the specified delay.
500 Server ErrorAn unexpected error occurred while creating the role.
503 UnavailableThe service is temporarily down for maintenance or overloaded.
Was this section helpful?

Example request

curl -X POST "{{env_base_uri}}/api/public/roles" \
  -H "Authorization: Bearer {YOUR_BEARER_TOKEN}" \
  -H "Accept: */*" \
  -H "Content-Type: application/json" \
  -d

Example response

201 CreatedRole was created successfully. The response includes the new role identifier.
{
  "data": "8e1c2f6a-7b40-4e2d-91c4-2cf03b9aa17e",
  "success": true
}

Designing roles

Start narrow. Grant only the privileges a role needs today and add more later — it's much safer than over-provisioning. Pair Workspace: Read All Content with task-specific privileges to give read-only auditors a useful view.