/{app_slug}/v1/admin/permissionsAuthCreate 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*stringSlug of the app.
Headers
Idempotency-KeystringRetry 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*stringResource name
Example: "project"
action*stringAction name
Example: "read"
descriptionstringFree-text description of the create permission, or `null`.
Example: "View projects"
Response · 201 Permission created.
id*stringUnique identifier of the permission.
app_id*stringApp scope. `null` for system permissions.
resource*stringResource half of the permission key (`resource.action`).
Example: "user"
action*stringAction half of the permission key (`resource.action`).
Example: "read"
description*stringFree-text description of the permission, or `null`.
created_at*string · date-timeWhen 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"
}