Create user

POST /users

Bearer auth

Create a new user with hierarchical authorization

application/json

Body Required

email string(email) Required

Email address (username will be generated automatically)
name string Required

Full name
user_role_ids array[string] Required

User role IDs to assign
organization_id string Required

Organization ID to assign user to
phone string

Phone number
custom_data object

Custom user data

Additional properties are allowed.

Responses

201 application/json

User created successfully
Hide response attributes Show response attributes object
- code integer
- message string
- data object
  
  Hide data attributes Show data attributes object
  
  id string
  
  User account ID
  
  logto_id string | null
  
  Logto user ID
  
  username string
  
  Username
  
  email string(email)
  
  Email address
  
  name string
  
  Full name
  
  phone string | null
  
  Phone number
  
  organization object | null
  
  Organization information
  
  Hide organization attributes Show organization attributes object | null
  
  id string
  
  Local database organization ID
  
  logto_id string
  
  Logto organization ID
  
  name string
  
  Organization name
  
  roles array[object]
  
  User roles with names
  
  Hide roles attributes Show roles attributes object
  
  id string
  
  Role ID
  
  name string
  
  Role name
  
  custom_data object
  
  Custom user data
  
  Additional properties are allowed.
  
  created_at string(date-time)
  
  Account creation timestamp
  
  updated_at string(date-time)
  
  Last update timestamp
  
  logto_synced_at string(date-time) | null
  
  Last Logto synchronization timestamp
  
  latest_login_at string(date-time) | null
  
  Timestamp of the last successful login via /auth/exchange endpoint. NULL means user has never logged in.
  
  deleted_at string(date-time) | null
  
  Soft delete timestamp (null if not deleted)
  
  suspended_at string(date-time) | null
  
  Suspension timestamp (null if not suspended)
400 application/json

Bad request - validation error
Hide response attributes Show response attributes object
- code integer
  
  HTTP error code
- message string
  
  Error message
- data object
  
  Hide data attributes Show data attributes object
  
  type string
  
  Type of error
  
  Values are validation_error or external_api_error.
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  key string
  
  Field name that failed validation
  
  message string
  
  Error code or message
  
  value string
  
  Value that failed validation
  
  details
  
  Additional error details
401 application/json

Unauthorized - invalid or missing token
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
403 application/json

Forbidden - insufficient permissions
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
422 application/json

Unprocessable entity - business logic error
Hide response attributes Show response attributes object
- code integer
  
  HTTP error code
- message string
  
  Error message
- data object
  
  Hide data attributes Show data attributes object
  
  type string
  
  Type of error
  
  Values are validation_error or external_api_error.
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  key string
  
  Field name that failed validation
  
  message string
  
  Error code or message
  
  value string
  
  Value that failed validation
  
  details
  
  Additional error details

POST /users

curl \
 --request POST 'https://api.your-domain.com/api/users' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"email":"john.doe@acme.com","name":"John Doe","user_role_ids":["rol_abc123def456","rol_xyz789abc123"],"organization_id":"org_xyz789","phone":"+39 333 123456","custom_data":{"position":"Senior Developer","department":"IT"}}'

Request examples

{
  "email": "john.doe@acme.com",
  "name": "John Doe",
  "user_role_ids": [
    "rol_abc123def456",
    "rol_xyz789abc123"
  ],
  "organization_id": "org_xyz789",
  "phone": "+39 333 123456",
  "custom_data": {
    "position": "Senior Developer",
    "department": "IT"
  }
}

Response examples (201)

{
  "code": 201,
  "message": "user created successfully",
  "data": {
    "id": "usr_123456789",
    "logto_id": "user_abc123def456",
    "username": "john.doe",
    "email": "john@example.com",
    "name": "John Doe",
    "phone": "+39 333 123456",
    "organization": {
      "id": "12345678-1234-1234-1234-123456789abc",
      "logto_id": "org_123456789",
      "name": "ACME Corp"
    },
    "roles": [
      {
        "id": "rol_admin_123",
        "name": "Admin"
      }
    ],
    "custom_data": {
      "position": "Senior Developer",
      "department": "IT"
    },
    "created_at": "2025-06-20T14:30:00Z",
    "updated_at": "2025-06-21T10:45:00Z",
    "logto_synced_at": "2025-06-21T10:45:00Z",
    "latest_login_at": "2025-06-21T15:30:45Z",
    "deleted_at": "2025-05-04T09:42:00Z",
    "suspended_at": "2025-05-04T09:42:00Z"
  }
}

Response examples (400)

{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}

Response examples (401)

{
  "code": 401,
  "message": "invalid token",
  "data": {}
}

Response examples (403)

{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}

Response examples (422)

{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}