---
title: "Create a new permission definition"
method: POST
path: "/permissions"
tags: ["Permission"]
---

# Create a new permission definition

`POST /permissions`

Creates a new permission entry in the tenant's permission catalog. Use this during initial RBAC setup or when introducing a new resource/action pair that roles can then be granted; it is typically called by administrators configuring access control, not by end-user workflows.

Preconditions: the caller must be authenticated and hold the CREATE_PERMISSION permission for the tenant.

Supply a request body with resource, action, and optionally description.

On success, returns the created permission including its server-assigned id. Note: createdAt and updatedAt are always null in the current implementation.

## Headers

- `tenant-id` string, required

## Request body

- PermissionCreateRequest — Request body for creating a new permission
  - `resource` string, required — Name of the resource this permission will govern (e.g., 'user', 'roster').
  - `action` string, required — Name of the action this permission will grant on the resource (e.g., 'read', 'create').
  - `description` string — Optional human-readable explanation of what the permission allows.

## Response `201`

The newly created permission, including its server-assigned id. Note: createdAt and updatedAt are always null in the current implementation.

- PermissionResponseDto — Permission information response
  - `id` string — Server-assigned unique identifier for the permission.
  - `resource` string — Name of the resource this permission governs (e.g. 'user', 'roster'). Mirrors the resource value supplied when the permission was created or last replaced.
  - `action` string — Name of the action this permission grants on the resource (e.g. 'read', 'create'). Mirrors the action value supplied when the permission was created or last replaced.
  - `description` string — Human-readable explanation of what the permission allows. Optional; may be null if it was not supplied at creation.
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `400` — Returned when the downstream data service rejects the request body as invalid (for example, a missing resource or action). This endpoint performs no local bean-validation, so the exact trigger is determined by the permissions data service.
- `500` — An unexpected error occurred while creating the permission, typically a downstream data-service failure. Retry the request or contact support if the error persists.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)