Skip to content
Authrim

Create an end user.

POST
/api/admin/users
Code sample: Shell / cURL 
curl --request POST \
  --url https://auth.example.com/api/admin/users \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "email": "hello@example.com", "name": "example", "given_name": "example", "family_name": "example", "nickname": "example", "preferred_username": "example", "picture": "https://example.com", "email_verified": true, "phone_number": "example", "phone_number_verified": true, "user_type": "example" }'

Allocate an account route and create a user in the selected tenant. Returns 201 only after Lookup directory publication is active. A transient publication delay returns 202 with a durable operation identifier that can be resumed by retrying the same request and Idempotency-Key. While elastic D1 capacity is being provisioned, or when the private Control binding is temporarily unavailable during rollout, or while a newly deployed runtime database binding is propagating, the endpoint returns 503 with Retry-After; clients must retry the same request and Idempotency-Key after that delay.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
X-Tenant-Id
string

Tenant selector for multi-tenant admin requests.

Idempotency-Key
required
string
>= 8 characters <= 128 characters

Stable replay-protection key for one account creation request.

Request Body required

Section titled “Request Body required ”
Media type application/json
object
email
required
string format: email
name
string
given_name
string
family_name
string
nickname
string
preferred_username
string
picture
string format: uri
email_verified
boolean
phone_number
string
phone_number_verified
boolean
user_type
string
key
additional properties
One of:
string
Example generated
{
  "email": "hello@example.com",
  "name": "example",
  "given_name": "example",
  "family_name": "example",
  "nickname": "example",
  "preferred_username": "example",
  "picture": "https://example.com",
  "email_verified": true,
  "phone_number": "example",
  "phone_number_verified": true,
  "user_type": "example"
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Admin end-user response.

Media type application/json
object
user
required
object
id
required
string
tenant_id
required
string
email
required
string | null format: email
name
required
string | null
given_name
required
string | null
family_name
required
string | null
nickname
required
string | null
preferred_username
required
string | null
picture
required
string | null format: uri
email_verified
required
boolean
phone_number
required
string | null
website
required
string | null
gender
required
string | null
birthdate
required
string | null
locale
required
string | null
zoneinfo
required
string | null
address_formatted
required
string | null
address_street_address
required
string | null
address_locality
required
string | null
address_region
required
string | null
address_postal_code
required
string | null
address_country
required
string | null
declared_residence
required
string | null
pii_class
required
string
Allowed values: PROFILE
phone_number_verified
required
boolean
user_type
required
string
is_active
required
boolean
pii_partition
required
string
pii_status
required
string
Allowed values: active deleted
lifecycle_state
required
string
created_at
required

Unix timestamp in milliseconds.

integer | null format: int64
updated_at
required

Unix timestamp in milliseconds.

integer | null format: int64
last_login_at
required
integer | null format: int64
status
required
string
Allowed values: active inactive suspended locked deleted
suspended_at
required
integer | null format: int64
suspended_until
required
integer | null format: int64
locked_at
required
integer | null format: int64
locked_until
required
integer | null format: int64
key
additional properties
key
additional properties
Example 
{
  "user": {
    "id": "user_123",
    "tenant_id": "default",
    "email": "user@example.com",
    "name": "Example User",
    "given_name": "Example",
    "family_name": "User",
    "nickname": null,
    "preferred_username": "example",
    "picture": "https://auth.example.com/api/avatars/user_123.png",
    "phone_number": null,
    "website": null,
    "gender": null,
    "birthdate": null,
    "locale": "en-US",
    "zoneinfo": "UTC",
    "address_formatted": null,
    "address_street_address": null,
    "address_locality": null,
    "address_region": null,
    "address_postal_code": null,
    "address_country": null,
    "declared_residence": null,
    "pii_class": "PROFILE",
    "email_verified": true,
    "phone_number_verified": false,
    "user_type": "end_user",
    "is_active": true,
    "pii_partition": "default",
    "pii_status": "active",
    "created_at": 1770000000000,
    "updated_at": 1770003600000,
    "last_login_at": null,
    "status": "active",
    "suspended_at": null,
    "suspended_until": null,
    "locked_at": null,
    "locked_until": null,
    "lifecycle_state": "active"
  }
}

202

Section titled “202 ”

Account data is durable but Lookup directory publication is still pending.

Media type application/json
object
status
required
string
Allowed value: pending
operation_id
required
string
>= 1 characters <= 256 characters
state
required
string
Allowed values: preparing reserved writing directory_pending succeeded blocked canceled
status_url
required
string
/^/api/admin/users/operations//
key
additional properties
Example 
{
  "status": "pending",
  "state": "preparing"
}

400

Section titled “400 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

409

Section titled “409 ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

503

Section titled “503 ”

Account capacity is being provisioned or the private Control binding is temporarily unavailable during rollout, or a newly deployed runtime database binding is still propagating. Retry the same idempotent request.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}

Headers

Section titled “Headers ”
Retry-After
integer
>= 1
Example 
10

Minimum suggested delay before retrying, in seconds.