Endpoints for user management. Including creating, updating, deleting, and querying users with flexible filters. In addition to the endpoints, see [🧑🚀 Manage users](https://docs.logto.io/docs/recipes/manage-users/) for more insights.
openapi: 3.0.1
info:
title: Logto API references Account center Users API
description: 'API references for Logto services.
Note: The documentation is for Logto Cloud. If you are using Logto OSS, please refer to the response of `/api/swagger.json` endpoint on your Logto instance.'
version: Cloud
servers:
- url: https://[tenant_id].logto.app/
description: Logto endpoint address.
security:
- OAuth2:
- all
tags:
- name: Users
description: Endpoints for user management. Including creating, updating, deleting, and querying users with flexible filters. In addition to the endpoints, see [🧑🚀 Manage users](https://docs.logto.io/docs/recipes/manage-users/) for more insights.
paths:
/api/users/{userId}:
get:
operationId: GetUser
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
- name: includeSsoIdentities
in: query
required: false
schema:
type: string
description: If it's provided with a truthy value (`true`, `1`, `yes`), each user in the response will include a `ssoIdentities` property containing a list of SSO identities associated with the user.
- name: includePasswordHash
in: query
required: false
schema:
type: string
description: If it's provided with a truthy value (`true`, `1`, `yes`), the response will include the `passwordDigest` and `passwordAlgorithm` fields. These fields are omitted by default for security reasons.
responses:
'200':
description: User data for the given ID.
content:
application/json:
schema:
type: object
required:
- id
- username
- primaryEmail
- primaryPhone
- name
- avatar
- customData
- identities
- lastSignInAt
- createdAt
- updatedAt
- profile
- applicationId
- isSuspended
properties:
id:
type: string
minLength: 1
maxLength: 12
username:
type: string
maxLength: 128
nullable: true
primaryEmail:
type: string
maxLength: 128
nullable: true
primaryPhone:
type: string
maxLength: 128
nullable: true
name:
type: string
maxLength: 128
nullable: true
avatar:
type: string
maxLength: 2048
nullable: true
customData:
type: object
description: arbitrary
identities:
type: object
additionalProperties:
type: object
required:
- userId
properties:
userId:
type: string
details:
type: object
description: arbitrary
lastSignInAt:
type: number
nullable: true
createdAt:
type: number
updatedAt:
type: number
profile:
type: object
properties:
familyName:
type: string
givenName:
type: string
middleName:
type: string
nickname:
type: string
preferredUsername:
type: string
profile:
type: string
website:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
address:
type: object
properties:
formatted:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
applicationId:
type: string
maxLength: 21
nullable: true
isSuspended:
type: boolean
hasPassword:
type: boolean
ssoIdentities:
type: array
items:
type: object
required:
- tenantId
- id
- userId
- issuer
- identityId
- detail
- createdAt
- updatedAt
- ssoConnectorId
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
userId:
type: string
minLength: 1
maxLength: 12
issuer:
type: string
minLength: 1
maxLength: 256
identityId:
type: string
minLength: 1
maxLength: 128
detail:
type: object
description: arbitrary
createdAt:
type: number
updatedAt:
type: number
ssoConnectorId:
type: string
minLength: 1
maxLength: 128
description: List of SSO identities associated with the user. Only available when the `includeSsoIdentities` query parameter is provided with a truthy value.
passwordDigest:
type: string
maxLength: 256
nullable: true
description: The hashed password of the user. Only present when `includePasswordHash` is provided with a truthy value. `null` if the user has no password set.
passwordAlgorithm:
type: string
enum:
- Argon2i
- Argon2id
- Argon2d
- SHA1
- SHA256
- MD5
- Bcrypt
- Legacy
nullable: true
description: The algorithm used to hash the password. Only present when `includePasswordHash` is provided with a truthy value. `null` if the user has no password set.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Get user
description: Get user data for the given ID.
patch:
operationId: UpdateUser
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
oneOf:
- type: string
format: regex
pattern: /^[A-Z_a-z]\w*$/
- type: string
format: empty
nullable: true
type: string
description: Updated username for the user. It should be unique across all users.
primaryEmail:
oneOf:
- type: string
format: regex
pattern: /^\S+@\S+\.\S+$/
- type: string
format: empty
nullable: true
type: string
description: Updated primary email address for the user. It should be unique across all users.
primaryPhone:
oneOf:
- type: string
format: regex
pattern: /^\d+$/
- type: string
format: empty
nullable: true
type: string
description: Updated primary phone number for the user. It should be unique across all users.
name:
oneOf:
- type: string
- type: string
format: empty
nullable: true
type: string
avatar:
oneOf:
- type: string
format: url
- type: string
format: empty
nullable: true
type: string
customData:
type: object
description: 'Custom data object to update for the given user ID. Note this will replace the entire custom data object.
If you want to perform a partial update, use the `PATCH /api/users/{userId}/custom-data` endpoint instead.'
profile:
type: object
properties:
familyName:
type: string
givenName:
type: string
middleName:
type: string
nickname:
type: string
preferredUsername:
type: string
profile:
type: string
website:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
address:
type: object
properties:
formatted:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
responses:
'200':
description: Updated user data for the given ID.
content:
application/json:
schema:
type: object
required:
- id
- username
- primaryEmail
- primaryPhone
- name
- avatar
- customData
- identities
- lastSignInAt
- createdAt
- updatedAt
- profile
- applicationId
- isSuspended
properties:
id:
type: string
minLength: 1
maxLength: 12
username:
type: string
maxLength: 128
nullable: true
primaryEmail:
type: string
maxLength: 128
nullable: true
primaryPhone:
type: string
maxLength: 128
nullable: true
name:
type: string
maxLength: 128
nullable: true
avatar:
type: string
maxLength: 2048
nullable: true
customData:
type: object
description: arbitrary
identities:
type: object
additionalProperties:
type: object
required:
- userId
properties:
userId:
type: string
details:
type: object
description: arbitrary
lastSignInAt:
type: number
nullable: true
createdAt:
type: number
updatedAt:
type: number
profile:
type: object
properties:
familyName:
type: string
givenName:
type: string
middleName:
type: string
nickname:
type: string
preferredUsername:
type: string
profile:
type: string
website:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
address:
type: object
properties:
formatted:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
applicationId:
type: string
maxLength: 21
nullable: true
isSuspended:
type: boolean
hasPassword:
type: boolean
ssoIdentities:
type: array
items:
type: object
required:
- tenantId
- id
- userId
- issuer
- identityId
- detail
- createdAt
- updatedAt
- ssoConnectorId
properties:
tenantId:
type: string
maxLength: 21
id:
type: string
minLength: 1
maxLength: 21
userId:
type: string
minLength: 1
maxLength: 12
issuer:
type: string
minLength: 1
maxLength: 256
identityId:
type: string
minLength: 1
maxLength: 128
detail:
type: object
description: arbitrary
createdAt:
type: number
updatedAt:
type: number
ssoConnectorId:
type: string
minLength: 1
maxLength: 128
passwordDigest:
type: string
maxLength: 256
nullable: true
passwordAlgorithm:
type: string
enum:
- Argon2i
- Argon2id
- Argon2d
- SHA1
- SHA256
- MD5
- Bcrypt
- Legacy
nullable: true
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable Content
summary: Update user
description: Update user data for the given ID. This method performs a partial update.
delete:
operationId: DeleteUser
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
responses:
'204':
description: User deleted successfully.
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Delete user
description: Delete user with the given ID. Note all associated data will be deleted cascadingly.
/api/users/{userId}/custom-data:
get:
operationId: ListUserCustomData
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
responses:
'200':
description: Custom data in JSON for the given user ID.
content:
application/json:
schema:
type: object
description: arbitrary
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
summary: Get user custom data
description: Get custom data for the given user ID.
patch:
operationId: UpdateUserCustomData
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customData
properties:
customData:
type: object
description: Partial custom data object to update for the given user ID.
responses:
'200':
description: Updated custom data in JSON for the given user ID.
content:
application/json:
schema:
type: object
description: arbitrary
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Update user custom data
description: Update custom data for the given user ID. This method performs a partial update of the custom data object.
/api/users/{userId}/logto-configs:
get:
operationId: ListUserLogtoConfigs
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
responses:
'200':
description: Returns the exposed user logto config fields, including MFA states (enabled, skipped, skipMfaOnSignIn) and passkey sign-in states (skipped).
content:
application/json:
schema:
type: object
required:
- mfa
- passkeySignIn
properties:
mfa:
type: object
required:
- skipped
- skipMfaOnSignIn
properties:
enabled:
type: boolean
skipped:
type: boolean
skipMfaOnSignIn:
type: boolean
passkeySignIn:
type: object
required:
- skipped
properties:
skipped:
type: boolean
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Get user logto config
description: Retrieve the exposed portion of a user's logto config. Includes MFA states (enabled, skipped, skipMfaOnSignIn) and passkey sign-in states (skipped).
patch:
operationId: UpdateUserLogtoConfigs
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mfa:
type: object
properties:
enabled:
type: boolean
description: Set whether MFA is enabled for the user.
skipped:
type: boolean
description: Set whether the user is marked as having skipped MFA binding.
additionalBindingSuggestionSkipped:
type: boolean
skipMfaOnSignIn:
type: boolean
description: Set whether the user has opted to skip MFA verification on sign-in. This is ignored when the MFA policy is mandatory.
passkeySignIn:
type: object
properties:
skipped:
type: boolean
description: Set whether the user has persistently skipped binding a passkey for sign-in.
responses:
'200':
description: The exposed logto config fields were updated successfully.
content:
application/json:
schema:
type: object
required:
- mfa
- passkeySignIn
properties:
mfa:
type: object
required:
- skipped
- skipMfaOnSignIn
properties:
enabled:
type: boolean
skipped:
type: boolean
skipMfaOnSignIn:
type: boolean
passkeySignIn:
type: object
required:
- skipped
properties:
skipped:
type: boolean
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Update user logto config
description: Update the exposed portion of a user's logto config. Supports updating MFA states (enabled, skipped, skipMfaOnSignIn) and passkey sign-in states (skipped). All fields are optional — only provided fields will be updated.
/api/users/{userId}/profile:
patch:
operationId: UpdateUserProfile
tags:
- Users
parameters:
- $ref: '#/components/parameters/userId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- profile
properties:
profile:
type: object
properties:
familyName:
type: string
givenName:
type: string
middleName:
type: string
nickname:
type: string
preferredUsername:
type: string
profile:
type: string
website:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
address:
type: object
properties:
formatted:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
description: Partial profile object to update for the given user ID.
responses:
'200':
description: Updated profile in JSON for the given user ID.
content:
application/json:
schema:
type: object
properties:
familyName:
type: string
givenName:
type: string
middleName:
type: string
nickname:
type: string
preferredUsername:
type: string
profile:
type: string
website:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
address:
type: object
properties:
formatted:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
summary: Update user profile
description: Update profile for the given user ID. This method performs a partial update of the profile object.
/api/users:
post:
operationId: CreateUser
tags:
- Users
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
primaryPhone:
type: string
format: regex
pattern: /^\d+$/
description: Primary phone number for the user. It should be unique across all users.
primaryEmail:
type: string
format: regex
pattern: /^\S+@\S+\.\S+$/
description: Primary email address for the user. It should be unique across all users.
username:
type: string
format: regex
pattern: /^[A-Z_a-z]\w*$/
description: Username for the user. It should be unique across all users.
password:
type: string
minLength: 1
description: Plain text password for the user.
passwordDigest:
type: string
maxLength: 256
description: In case you already have the password digests and not the passwords, you can use them for the newly created user via this property. The algorithm can be specified using the `passwordAlgorithm` property. For `Legacy`, pass a JSON string in the format `[algorithm, args, encryptedPassword]`, where `args` is a string array that MUST contain an `@` placeholder, which will be replaced by the plain text password at runtime. For PBKDF2 under `Legacy`, `args` is expected to be in the order `[salt, iterations, keylen, digest, '@']`. The salt supports a plain string or a `hex:`-prefixed hex string (for binary salt bytes).
passwordAlgorithm:
type: string
enum:
- Argon2i
- Argon2id
- Argon2d
- SHA1
- SHA256
- MD5
- Bcrypt
- Legacy
description: The hash algorithm used for the password. It should be one of the supported algorithms, including `Legacy` for custom legacy expressions. Should the encryption algorithm differ from `Argon2i`, it will automatically be upgraded to `Argon2i` upon the user's next sign-in.
name:
type: string
avatar:
oneOf:
- type: string
format: url
- type: string
format: empty
nullable: true
type: string
customData:
type: object
description: arbitrary
profile:
type: object
properties:
familyName:
type: string
givenName:
type: string
middleName:
type: string
nickname:
type: string
preferredUsername:
type: string
profile:
type: string
website:
type: string
gender:
type: string
birthdate:
type: string
zoneinfo:
type: string
locale:
type: string
address:
type: object
properties:
formatted:
type: string
streetAddress:
type: string
locality:
type: string
region:
type: string
postalCode:
type: string
country:
type: string
# --- truncated at 32 KB (165 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-users-api-openapi.yml