Auth API reference

Auth API · Consumer-Admin

post/{app_slug}/v1/admin/usersAuth

Provision a new end-user

Create an account in this app. Distinct from the public `/auth/signup`: no session is issued, no password is required (when omitted, the customer triggers a password-reset to finish onboarding), and the primary email contact starts unverified — the customer is responsible for kicking off the verification flow via `/auth/request-verification` or `/auth/send-verification-email`. The `roleName` defaults to the app's `signup_default_role`. What is NOT distinct: the password policy. A supplied `password` goes through the same app-configured rules, the same common-password deny-list and the same breach check as `/auth/signup`.

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

Request body

email*string

Primary email — becomes the account's primary email contact (unverified).

Example: "ada@example.com"

usernamestring

Username inside the app. Derived from the email local-part if omitted.

Example: "john_doe"

display_namestring

Human-readable display name.

passwordstring

Optional initial password. When omitted, the account has no credential — the customer triggers the password-reset flow to onboard the user. When supplied it must satisfy the SAME rules as `/auth/signup`: the app-configured length and character classes, the common-password deny-list (400 `PASSWORD_TOO_COMMON`) and, unless the app sets `password_breach_check` to `off` or `warn`, the breach corpus (400 `PASSWORD_BREACHED`).

role_namestring

Role to assign. Defaults to the app's `signup_default_role`.

Response · 201 Created end-user record.

id*string

Unique identifier of the user.

username*string

The end user's username, unique within the app.

display_name*string

Human-readable name of the user.

email*string

Email address.

email_verified*boolean

Whether the email address was marked verified at creation.

role*string

App-level role name of the user, or `null` for none.

status*string

Account status: `active`, `suspended` or `deactivated`.

created_at*string · date-time

When the user was created (ISO 8601).

password_warningsarray

Present only when the app runs `password_breach_check: 'warn'` and the supplied password was found in the breach corpus. The account IS created; in `'block'` mode the request would have been rejected with 400 `PASSWORD_BREACHED` instead. Same shape as the signup response.

Example: ["breached"]

Example

Request

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

{
  "email": "ada@example.com",
  "username": "john_doe",
  "display_name": "string",
  "password": "string",
  "role_name": "string"
}

Response

{
  "id": "string",
  "username": "string",
  "display_name": "string",
  "email": "string",
  "email_verified": false,
  "role": "string",
  "status": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "password_warnings": [
    "breached"
  ]
}