Auth API reference

Auth API · Consumer-Admin-Permissions

post/{app_slug}/v1/admin/permissionsAuth

Create a custom permission

Inserts a `<resource>.<action>` row in the per-app permission catalogue. The resource and action segments must each match `^[a-z][a-z0-9_-]{1,47}$`. Conflicts with a system permission name return 409. Customers usually then bind the new permission to a role via `PUT /admin/roles/:roleName/permissions`.

Path parameters

app_slug*string

Slug of the app.

Headers

Idempotency-Keystring

Retry safety: a repeat with the same key and body replays the first response instead of creating a permission again. Same key with a different body: 409 `IDEMPOTENCY_KEY_REUSE`. 24 h window.

Request body

resource*string

Resource name

Example: "project"

action*string

Action name

Example: "read"

descriptionstring

Free-text description of the create permission, or `null`.

Example: "View projects"

Response · 201 Permission created.

id*string

Unique identifier of the permission.

app_id*string

App scope. `null` for system permissions.

resource*string

Resource half of the permission key (`resource.action`).

Example: "user"

action*string

Action half of the permission key (`resource.action`).

Example: "read"

description*string

Free-text description of the permission, or `null`.

created_at*string · date-time

When the permission was created (ISO 8601).

Example

Request

POST https://api.auth.productcraft.co/{app_slug}/v1/admin/permissions
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "resource": "project",
  "action": "read",
  "description": "View projects"
}

Response

{
  "id": "string",
  "app_id": "string",
  "resource": "user",
  "action": "read",
  "description": "string",
  "created_at": "2026-01-01T00:00:00.000Z"
}