Skip to main content

Create Role

Create a new role in Guardhouse.

Authentication​

This endpoint requires a bearer access token for the System API.

Endpoint​

POST /api/v1/roles
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request​

Headers​

HeaderRequiredDescription
AuthorizationYesBearer token for a System API client
Content-TypeYesMust be application/json

Query Parameters​

This endpoint does not accept query parameters.

Request Body​

{
"key": "administrator",
"name": "Administrator",
"description": "Full administrative access"
}

Request Fields​

FieldTypeRequiredDescription
keystringYesRole key. Must contain only lowercase letters and be 2 to 30 characters long.
namestringYesDisplay name of the role. Must be 3 to 100 characters long.
descriptionstringYesRole description. Must be 3 to 120 characters long.

Validation Rules​

  • key must be 2 to 30 characters long
  • key can contain lowercase letters only: a-z
  • key cannot have leading or trailing whitespace
  • name must be 3 to 100 characters long
  • name cannot have leading or trailing whitespace
  • description must be 3 to 120 characters long
  • description cannot have leading or trailing whitespace

Response​

200 OK​

Returns the identifier of the created role.

{
"roleId": 12
}

Response Fields​

FieldTypeDescription
roleIdintegerIdentifier of the created role

Errors​

StatusWhen it happens
401 UnauthorizedThe bearer token is missing, invalid, or expired
403 ForbiddenThe token is valid but does not have access to this endpoint
409 ConflictA conflicting role already exists

409 Example​

Role with key administrator already exists

Example​

cURL​

curl -X POST "https://your-tenant.guardhouse.cloud/api/v1/roles" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"key": "administrator",
"name": "Administrator",
"description": "Full administrative access"
}'

.NET SDK​

using Guardhouse.SDK.Models.Roles;
using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapPost("/example/roles", async (IGuardhouseRolesClient rolesClient) =>
{
var createdRole = await rolesClient.CreateRoleAsync(new CreateRoleRequest
{
Key = "administrator",
Name = "Administrator",
Description = "Full administrative access"
});

return Results.Ok(createdRole);
});

Python (raw HTTP)​

# The Python beta does not expose System API helpers.
# Use raw HTTP for now.
#
# Example shape:
# import requests
# response = requests.post(
# "https://your-tenant.guardhouse.cloud/api/v1/roles",
# headers={
# "Authorization": "Bearer YOUR_ACCESS_TOKEN",
# "Content-Type": "application/json",
# },
# json={
# "key": "administrator",
# "name": "Administrator",
# "description": "Full administrative access",
# },
# )

Notes​