/{app_slug}/v1/admin/rolesAuthCreate 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*stringSlug of the app.
Headers
Idempotency-KeystringRetry 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*stringName of the role.
Example: "editor"
descriptionstringFree-text description of the role, or `null`.
Example: "Can edit content"
Response · 201 Role created.
id*stringUnique identifier of the role.
app_id*stringThe Auth app the role belongs to.
name*stringName of the role.
description*stringFree-text description of the role, or `null`.
is_system*booleanTrue for the built-in roles every app has; they cannot be renamed or deleted.
created_at*string · date-timeWhen the role was created (ISO 8601).
updated_at*string · date-timeWhen 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"
}