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

Header	Required	Description
Authorization	Yes	Bearer token for a System API client
Content-Type	Yes	Must be application/json

Query Parameters

This endpoint does not accept query parameters.

Request Body

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

Request Fields

Field	Type	Required	Description
key	string	Yes	Role key. Must contain only lowercase letters and be 2 to 30 characters long.
name	string	Yes	Display name of the role. Must be 3 to 100 characters long.
description	string	Yes	Role 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

Field	Type	Description
roleId	integer	Identifier of the created role

Errors

Status	When it happens
401 Unauthorized	The bearer token is missing, invalid, or expired
403 Forbidden	The token is valid but does not have access to this endpoint
409 Conflict	A 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 SDK

# SDK support is in development.
# 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

• The key is normalized to lowercase for storage.
• Use Get Roles or Get Role By ID to retrieve created roles.
• Use Getting Access Credentials if you still need to configure a System API client or obtain a token.