Skip to content
Torii docs

Create user

POST
/api/server/v1/users
 
curl --request POST \
  --url https://api.torii.so/api/server/v1/users \
  --header 'Content-Type: application/json' \
  --data '{ "email": "ada@example.com", "password": "correct horse battery staple", "firstName": "Ada", "lastName": "Lovelace", "publicMetadata": { "plan": "free" }, "privateMetadata": { "stripeId": "cus_123" }, "unsafeMetadata": { "onboardingStep": 0 } }'

Creates an end-user in your environment. All body fields are optional; supply at minimum an email if you want the user to be able to sign in via email + password.

Request Body required

Section titled “Request Body required ”
Media type application/json

Request body for creating an end-user in your environment. All fields are optional; supply at minimum an email if you want the user to be able to sign in via email + password.

object
email

Primary email for the new user. If omitted, the user is created without a sign-in identity.

string | null
Example 
ada@example.com
password

Initial password. Subject to the environment’s password policy. Omit to create a passwordless user (e.g. social-only).

string | null
Example 
correct horse battery staple
firstName

First (given) name to seed on the profile.

string | null
Example 
Ada
lastName

Last (family) name to seed on the profile.

string | null
Example 
Lovelace
publicMetadata
required

Initial public metadata (SDK-readable, server-written). Max 512 bytes.

object
key
additional properties
any
Example 
{
  "plan": "free"
}
privateMetadata
required

Initial private metadata (server-only). Max 4096 bytes.

object
key
additional properties
any
Example 
{
  "stripeId": "cus_123"
}
unsafeMetadata
required

Initial unsafe metadata (end-user writable). Max 512 bytes.

object
key
additional properties
any
Example 
{
  "onboardingStep": 0
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

The created user.

Media type application/json

An end-user, including server-only private metadata. Returned only on the secret-key backend API.

object
id
required

Unique identifier for this user.

string format: uuid
environmentId
required

Identifier of the environment this user belongs to.

string format: uuid
name

Full name on the profile, if any.

string | null
firstName

First (given) name on the profile, if any.

string | null
lastName

Last (family) name on the profile, if any.

string | null
locale

Preferred locale for emails and UI messages.

string | null
Allowed values: en da
status
required

Lifecycle status of the user (e.g. active, banned).

string
Allowed values: active banned deleted
createdAt
required

When this user was created (ISO-8601 UTC).

string format: date-time
updatedAt
required

When this user was last modified (ISO-8601 UTC).

string format: date-time
email

Primary email on the profile, if any.

string | null
emailVerifiedAt

When this user’s primary email was verified, if it has been verified.

string | null format: date-time
deletedAt

When this user was deleted, if soft-deleted. Null for active users.

string | null format: date-time
publicMetadata
required

Public metadata: readable by the SDK, writable only server-side.

object
key
additional properties
any
privateMetadata
required

Private metadata: server-only. Never exposed to the SDK or in a JWT.

object
key
additional properties
any
unsafeMetadata
required

Unsafe metadata: readable and writable by the end-user via the SDK.

object
key
additional properties
any
Example 
{
  "id": "01931a73-8b00-7000-8000-000000000000",
  "environmentId": "01931a72-0000-7000-8000-000000000000",
  "name": "Ada Lovelace",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "locale": "en",
  "status": "active",
  "createdAt": "2026-05-16T09:30:00Z",
  "updatedAt": "2026-05-16T10:00:00Z",
  "email": "ada@example.com",
  "emailVerifiedAt": "2026-05-16T09:35:00Z",
  "deletedAt": "2026-05-20T12:00:00Z",
  "publicMetadata": {
    "plan": "pro"
  },
  "privateMetadata": {
    "stripeId": "cus_123"
  },
  "unsafeMetadata": {
    "onboardingStep": 2
  }
}

400

Section titled “400 ”

Invalid body (e.g. weak password, malformed email).

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

401

Section titled “401 ”

Missing or invalid secret key.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

409

Section titled “409 ”

Another user with this email already exists in the environment.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}