Skip to main content

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​

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

Request Fields​

FieldTypeRequiredDescription
keystringYesPermission key. Must be 3 to 30 characters long, use lowercase letters and dots only, and start and end with a lowercase letter.
namestringYesDisplay name of the permission. Must be 3 to 120 characters long.
descriptionstringYesPermission 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​

FieldTypeDescription
idintegerIdentifier of the created permission

Errors​

StatusWhen it happens
400 Bad RequestThe request is invalid or the permission key is rejected
401 UnauthorizedThe bearer token is missing, invalid, or expired
403 ForbiddenThe token is valid but does not have access to this endpoint
409 ConflictA 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 (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/permissions",
# headers={
# "Authorization": "Bearer YOUR_ACCESS_TOKEN",
# "Content-Type": "application/json",
# },
# json={
# "key": "users.read",
# "name": "Users Read",
# "description": "Allows reading user records",
# },
# )

Notes​