Create Permission

Create a new permission in Guardhouse.

Authentication

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

Endpoint

POST /api/v1/permissions
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": "users.read",
  "name": "Users Read",
  "description": "Allows reading user records"
}

Request Fields

Field	Type	Required	Description
key	string	Yes	Permission key. Must be 3 to 30 characters long, use lowercase letters and dots only, and start and end with a lowercase letter.
name	string	Yes	Display name of the permission. Must be 3 to 120 characters long.
description	string	Yes	Permission description. Must be 3 to 120 characters long.

Validation Rules

• key must be 3 to 30 characters long
• key can contain lowercase letters and dots only
• key must start and end with a lowercase letter
• key cannot have leading or trailing whitespace
• name must be 3 to 120 characters long
• name cannot have leading or trailing whitespace
• description must be 3 to 120 characters long
• description cannot have leading or trailing whitespace
• The submitted key must also satisfy Guardhouse permission naming rules

Response

200 OK

Returns the identifier of the created permission.

{
  "id": 15
}

Response Fields

Field	Type	Description
id	integer	Identifier of the created permission

Errors

Status	When it happens
400 Bad Request	The request is invalid or the permission key is rejected
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 permission with the same key already exists

409 Example

Permission already exists

Example

cURL

curl -X POST "https://your-tenant.guardhouse.cloud/api/v1/permissions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "users.read",
    "name": "Users Read",
    "description": "Allows reading user records"
  }'

.NET SDK

using Guardhouse.SDK.Models.Permissions;
using Guardhouse.SDK.Services;

// Assumes AddGuardhouseClientWithApiClients(...) is already configured.
app.MapPost("/example/permissions", async (IGuardhousePermissionsClient permissionsClient) =>
{
    var createdPermission = await permissionsClient.CreatePermissionAsync(new CreatePermissionRequest
    {
        Key = "users.read",
        Name = "Users Read",
        Description = "Allows reading user records"
    });

    return Results.Ok(createdPermission);
});

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/permissions",
#     headers={
#         "Authorization": "Bearer YOUR_ACCESS_TOKEN",
#         "Content-Type": "application/json",
#     },
#     json={
#         "key": "users.read",
#         "name": "Users Read",
#         "description": "Allows reading user records",
#     },
# )

Notes

• Use a stable permission key because it may be referenced by role assignments.
• Use Get Permission By ID or Get Permissions to retrieve created permissions.
• Use Getting Access Credentials if you still need to configure a System API client or obtain a token.