Auth API reference

Auth API · Consumer-Admin-Roles

post/{app_slug}/v1/admin/rolesAuth

Create a role

Creates a role with no permissions bound yet. Use `PUT /:roleName/permissions` to attach a permission set after creation — that route also runs caller-narrowing so an EndUser admin can't grant verbs they don't themselves hold.

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 role again. Same key with a different body: 409 `IDEMPOTENCY_KEY_REUSE`. 24 h window.

Request body

name*string

Name of the role.

Example: "editor"

descriptionstring

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

Example: "Can edit content"

Response · 201 Role created.

id*string

Unique identifier of the role.

app_id*string

The Auth app the role belongs to.

name*string

Name of the role.

description*string

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

is_system*boolean

True for the built-in roles every app has; they cannot be renamed or deleted.

created_at*string · date-time

When the role was created (ISO 8601).

updated_at*string · date-time

When the role was last changed (ISO 8601).

Example

Request

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

{
  "name": "editor",
  "description": "Can edit content"
}

Response

{
  "id": "string",
  "app_id": "string",
  "name": "string",
  "description": "string",
  "is_system": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}