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 description: User data to create a new user. All properties are optional. responses: '200': description: User data for the newly created user. 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: Create user description: Create a new user with the given data. get: operationId: ListUsers tags: - Users parameters: - name: page in: query description: Page number (starts from 1). required: false schema: type: integer minimum: 1 default: 1 - name: page_size in: query description: Entries per page. required: false schema: type: integer minimum: 1 default: 20 - name: search_params in: query description: Search query parameters. required: false schema: type: object additionalProperties: type: string explode: true responses: '200': description: An array of users that match the given criteria. content: application/json: schema: type: array items: 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 summary: Get users description: 'Get users with filters and pagination. Logto provides a very flexible way to query users. You can filter users by almost any fields with multiple modes. To learn more about the query syntax, please refer to [Advanced user search](https://docs.logto.io/docs/recipes/manage-users/advanced-user-search/).' /api/users/{userId}/password: patch: operationId: UpdateUserPassword tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - password properties: password: type: string minLength: 1 description: New password for the user. responses: '200': description: User password updated successfully. 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 '422': description: Unprocessable Content summary: Update user password description: Update user password for the given ID. /api/users/{userId}/password/verify: post: operationId: VerifyUserPassword tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - password properties: password: type: string minLength: 1 description: Password to verify. responses: '204': description: User password matches. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: User password does not match. summary: Verify user password description: Test if the given password matches the user's password. /api/users/{userId}/has-password: get: operationId: GetUserHasPassword tags: - Users parameters: - $ref: '#/components/parameters/userId' responses: '200': description: The result of the check. content: application/json: schema: type: object required: - hasPassword properties: hasPassword: type: boolean '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Check if user has password description: Check if the user with the given ID has a password set. /api/users/{userId}/is-suspended: patch: operationId: UpdateUserIsSuspended tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - isSuspended properties: isSuspended: type: boolean description: New suspension status for the user. responses: '200': description: User suspension status updated successfully. 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 summary: Update user suspension status description: Update user suspension status for the given ID. /api/users/{userId}/roles: get: operationId: ListUserRoles tags: - Users parameters: - $ref: '#/components/parameters/userId' - name: page in: query description: Page number (starts from 1). required: false schema: type: integer minimum: 1 default: 1 - name: page_size in: query description: Entries per page. required: false schema: type: integer minimum: 1 default: 20 - name: search_params in: query description: Search query parameters. required: false schema: type: object additionalProperties: type: string explode: true responses: '200': description: An array of API resource roles assigned to the user. content: application/json: schema: type: array items: type: object required: - tenantId - id - name - description - type - isDefault properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 128 description: type: string minLength: 1 maxLength: 128 type: type: string enum: - User - MachineToMachine isDefault: type: boolean '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Get roles for user description: Get API resource roles assigned to the user with pagination. post: operationId: AssignUserRoles tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - roleIds properties: roleIds: type: array items: type: string minLength: 1 description: An array of API resource role IDs to assign. responses: '201': description: The API resource roles has been assigned to the user. content: application/json: schema: type: object required: - roleIds - addedRoleIds properties: roleIds: type: array items: type: string minLength: 1 description: An array of API resource role IDs requested for assignment. addedRoleIds: type: array items: type: string minLength: 1 description: An array of API resource role IDs newly assigned to the user. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Assign roles to user description: Assign API resource roles to the user. The roles will be added to the existing roles. put: operationId: ReplaceUserRoles tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - roleIds properties: roleIds: type: array items: type: string minLength: 1 description: An array of API resource role IDs to assign. responses: '200': description: The API resource roles has been updated for the user successfully. content: application/json: schema: type: object required: - roleIds properties: roleIds: type: array items: type: string minLength: 1 description: An array of API resource role IDs assigned to the user. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Update roles for user description: Update API resource roles assigned to the user. This will replace the existing roles. /api/users/{userId}/roles/{roleId}: delete: operationId: DeleteUserRole tags: - Users parameters: - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/roleId' responses: '204': description: The API resource role has been removed from the user. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Remove role from user description: Remove an API resource role from the user. /api/users/{userId}/identities/{target}: put: operationId: ReplaceUserIdentity tags: - Users parameters: - $ref: '#/components/parameters/userId' - name: target in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - userId properties: userId: type: string description: The user's social identity ID. details: type: object description: The user's social identity details. responses: '200': description: The identity is updated. content: application/json: schema: type: object additionalProperties: type: object required: - userId properties: userId: type: string details: type: object description: arbitrary '201': description: The identity is created. content: application/json: schema: type: object additionalProperties: type: object required: - userId properties: userId: type: string details: type: object description: arbitrary '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Update social identity of user description: Directly update a social identity of the user. delete: operationId: DeleteUserIdentity tags: - Users parameters: - $ref: '#/components/parameters/userId' - name: target in: path required: true schema: type: string responses: '200': description: The identity is deleted from the user. 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 '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Delete social identity from user description: Delete a social identity from the user. get: operationId: GetUserIdentity tags: - Users parameters: - $ref: '#/components/parameters/userId' - name: target in: path required: true schema: type: string - name: includeTokenSecret in: query required: false schema: type: string description: Whether to include the token secret in the response. Defaults to false. Token storage must be supported and enabled by the connector to return the token secret. responses: '200': description: Returns the user's social identity and associated token storage. content: application/json: schema: type: object required: - identity properties: identity: type: object required: - userId properties: userId: type: string details: type: object description: arbitrary description: The user's social identity. tokenSecret: type: object required: - tenantId - id - userId - type - metadata - createdAt - updatedAt - connectorId - identityId - target properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 userId: type: string minLength: 1 maxLength: 21 type: type: string format: '"federated_token_set"' metadata: type: object required: - hasRefreshToken properties: scope: type: string expiresAt: type: number tokenType: type: string hasRefreshToken: type: boolean createdAt: type: number updatedAt: type: number connectorId: type: string identityId: type: string target: type: string description: 'The desensitized token set secret associated with the user''s social identity. This field is included only if the `includeTokenSecret` query parameter is provided and the corresponding connector has token storage enabled.' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: User social identity not found. summary: Retrieve a user's social identity and associated token storage . description: This API retrieves the social identity and its associated token set for the specified user from the Logto Secret Vault. The token set will only be available if token storage is enabled for the corresponding social connector. /api/users/{userId}/identities: post: operationId: CreateUserIdentity tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - connectorId - connectorData properties: connectorId: type: string description: The Logto connector ID. connectorData: type: object additionalProperties: example: {} description: A json object constructed from the url query params returned by the social platform. Typically it contains `code`, `state` and `redirectUri` fields. responses: '200': description: A new identity is linked to the user. content: application/json: schema: type: object additionalProperties: type: object required: - userId properties: userId: type: string details: type: object description: arbitrary '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Link social identity to user description: 'Link authenticated user identity from a social platform to a Logto user. The usage of this API is usually coupled with `POST /connectors/:connectorId/authorization-uri`. With the help of these pair of APIs, you can implement a user profile page with the link social account feature in your application. Note: Currently due to technical limitations, this API does not support the following connectors that rely on Logto interaction session: `@logto/connector-apple`, `@logto/connector-saml`, `@logto/connector-oidc` and `@logto/connector-oauth`.' /api/users/{userId}/organizations: get: operationId: ListUserOrganizations tags: - Users parameters: - $ref: '#/components/parameters/userId' responses: '200': description: An array of organizations that the user is a member of. content: application/json: schema: type: array items: type: object required: - tenantId - id - name - description - customData - isMfaRequired - color - branding - customCss - createdAt - organizationRoles properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 128 description: type: string maxLength: 256 nullable: true customData: type: object description: arbitrary isMfaRequired: type: boolean color: type: object properties: primaryColor: type: string format: regex pattern: /^#[\da-f]{3}([\da-f]{3})?$/i isDarkModeEnabled: type: boolean darkPrimaryColor: type: string format: regex pattern: /^#[\da-f]{3}([\da-f]{3})?$/i branding: type: object properties: logoUrl: type: string format: url darkLogoUrl: type: string format: url favicon: type: string format: url darkFavicon: type: string format: url customCss: type: string nullable: true createdAt: type: number organizationRoles: type: array items: type: object required: - id - name properties: id: type: string name: type: string '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Get organizations for a user description: Get all organizations that the user is a member of. In each organization object, the user's roles in that organization are included in the `organizationRoles` array. /api/users/{userId}/grants: get: operationId: ListUserGrants tags: - Users parameters: - $ref: '#/components/parameters/userId' - name: appType in: query required: false schema: type: string enum: - firstParty - thirdParty description: Application type filter. Use 'thirdParty' to list third-party app grants only, or 'firstParty' to list first-party app grants only. If omitted, grants from all applications are returned. responses: '200': description: Return non-expired grants of the user. Results are filtered by app type when `appType` is provided. content: application/json: schema: type: object required: - grants properties: grants: type: array items: type: object required: - id - payload - expiresAt properties: id: type: string payload: type: object required: - exp - iat - jti - kind - clientId - accountId properties: exp: type: number iat: type: number jti: type: string kind: type: string format: '"Grant"' clientId: type: string accountId: type: string expiresAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '500': description: Internal Server Error summary: Get user active grants description: Retrieve all non-expired grants of the user. Optionally filter by application type via `appType`; when omitted, grants from all application types are returned. /api/users/{userId}/grants/{grantId}: delete: operationId: DeleteUserGrant tags: - Users parameters: - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/grantId' responses: '204': description: Grant revoked successfully. If the grant already expired, this endpoint returns success without token-chain changes. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Grant not found. This can occur if the grant ID is invalid, or the grant does not belong to the user. '500': description: Internal Server Error summary: Revoke a user grant description: Revoke a specific grant and its associated token chain by grant ID. Also removes the matching session authorization entry for this grant from the related active session. The grant must belong to the user. /api/users/{userId}/mfa-verifications: get: operationId: ListUserMfaVerifications tags: - Users parameters: - $ref: '#/components/parameters/userId' responses: '200': description: An array of MFA verifications for the user. content: application/json: schema: type: array items: type: object required: - id - createdAt - type properties: id: type: string createdAt: type: string lastUsedAt: type: string type: type: string enum: - Totp - WebAuthn - BackupCode - EmailVerificationCode - PhoneVerificationCode agent: type: string name: type: string remainCodes: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Get user's MFA verifications description: Get a user's existing MFA verifications for a given user ID. post: operationId: CreateUserMfaVerification tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: oneOf: - type: object required: - type properties: type: type: string format: '"Totp"' secret: type: string - type: object required: - type properties: type: type: string format: '"BackupCode"' codes: type: array items: type: string - type: object properties: type: type: string description: The type of MFA verification to create. secret: type: string description: The secret for the MFA verification, if not provided, a new secret will be generated. required: - type - type: object properties: type: type: string description: The type of MFA verification to create. codes: type: array items: type: string description: The backup codes for the MFA verification, if not provided, a new group of backup codes will be generated. required: - type responses: '200': description: The MFA verification that was created. content: application/json: schema: oneOf: - type: object required: - type - secret - secretQrCode properties: type: type: string format: '"Totp"' secret: type: string secretQrCode: type: string - type: object required: - type - codes properties: type: type: string format: '"BackupCode"' codes: type: array items: type: string '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '422': description: Unprocessable Content summary: Create an MFA verification for a user description: Create a new MFA verification for a given user ID. /api/users/{userId}/mfa-verifications/{verificationId}: delete: operationId: DeleteUserMfaVerification tags: - Users parameters: - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/verificationId' responses: '204': description: The MFA verification was deleted successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Delete an MFA verification for a user description: Delete an MFA verification for the user with the given verification ID. The verification ID must be associated with the given user ID. /api/users/{userId}/personal-access-tokens: get: operationId: ListUserPersonalAccessTokens tags: - Users parameters: - $ref: '#/components/parameters/userId' responses: '200': description: A list of personal access tokens. content: application/json: schema: type: array items: type: object required: - tenantId - userId - name - value - createdAt - expiresAt properties: tenantId: type: string maxLength: 21 userId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 value: type: string minLength: 1 maxLength: 64 createdAt: type: number expiresAt: type: number nullable: true '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Get personal access tokens description: Get all personal access tokens for the user. post: operationId: CreateUserPersonalAccessToken tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 256 description: The personal access token name. Must be unique within the user. expiresAt: type: number nullable: true description: The epoch time in milliseconds when the token will expire. If not provided, the token will never expire. responses: '201': description: The personal access token was added successfully. content: application/json: schema: type: object required: - tenantId - userId - name - value - createdAt - expiresAt properties: tenantId: type: string maxLength: 21 userId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 value: type: string minLength: 1 maxLength: 64 createdAt: type: number expiresAt: type: number nullable: true '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The personal access token name is already in use. summary: Add personal access token description: Add a new personal access token for the user. patch: operationId: UpdatePersonalAccessTokenName tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 256 description: The new token name. Must be unique within the user. currentName: type: string description: The current name of the token to update. responses: '200': description: The token was updated successfully. content: application/json: schema: type: object required: - tenantId - userId - name - value - createdAt - expiresAt properties: tenantId: type: string maxLength: 21 userId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 value: type: string minLength: 1 maxLength: 64 createdAt: type: number expiresAt: type: number nullable: true '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Update personal access token description: Update a token for the user by name. /api/users/{userId}/personal-access-tokens/{name}: delete: operationId: DeleteUserPersonalAccessToken tags: - Users parameters: - $ref: '#/components/parameters/userId' - name: name in: path required: true schema: type: string description: The name of the token. responses: '204': description: The token was deleted successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Delete personal access token description: 'Delete a token for the user by name using the legacy path parameter. Deprecated: use the POST /delete endpoint instead to avoid url name encoding issues.' patch: operationId: UpdateUserPersonalAccessToken tags: - Users parameters: - $ref: '#/components/parameters/userId' - name: name in: path required: true schema: type: string description: The current name of the token. requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string minLength: 1 maxLength: 256 description: The new token name. Must be unique within the user. responses: '200': description: The token was updated successfully. content: application/json: schema: type: object required: - tenantId - userId - name - value - createdAt - expiresAt properties: tenantId: type: string maxLength: 21 userId: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 256 value: type: string minLength: 1 maxLength: 64 createdAt: type: number expiresAt: type: number nullable: true '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Update personal access token description: 'Update a token for the user by name using the legacy path parameter. Deprecated: use the PATCH /personal-access-tokens endpoint instead to avoid url name encoding issues.' /api/users/{userId}/personal-access-tokens/delete: post: operationId: DeletePersonalAccessTokenPost tags: - Users parameters: - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: The name of the token to delete. responses: '204': description: The token was deleted successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found summary: Delete personal access token description: Delete a token for the user by name. /api/users/{userId}/sso-identities/{ssoConnectorId}: get: operationId: GetUserSsoIdentity tags: - Users parameters: - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/ssoConnectorId' - name: includeTokenSecret in: query required: false schema: type: string description: Whether to include the token secret in the response. Defaults to false. Token storage must be supported and enabled by the connector to return the token secret. responses: '200': description: Returns the user's enterprise SSO identity and associated token secret. content: application/json: schema: type: object required: - ssoIdentity properties: ssoIdentity: 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: The user's enterprise SSO identity. tokenSecret: type: object required: - tenantId - id - userId - type - metadata - createdAt - updatedAt - ssoConnectorId - issuer - identityId properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 userId: type: string minLength: 1 maxLength: 21 type: type: string format: '"federated_token_set"' metadata: type: object required: - hasRefreshToken properties: scope: type: string expiresAt: type: number tokenType: type: string hasRefreshToken: type: boolean createdAt: type: number updatedAt: type: number ssoConnectorId: type: string issuer: type: string identityId: type: string description: 'The desensitized token set secret associated with the user''s SSO identity. This field is included only if the `includeTokenSecret` query parameter is provided and the corresponding connector has token storage enabled.' '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: User enterprise SSO identity not found. summary: Retrieve a user's enterprise SSO identity and associated token secret (if token storage is enabled). description: This API retrieves the user's enterprise SSO identity and associated token set record from the Logto Secret Vault. The token set will only be available if token storage is enabled for the corresponding SSO connector. /api/users/{userId}/all-identities: get: operationId: ListUserAllIdentities tags: - Users parameters: - $ref: '#/components/parameters/userId' - name: includeTokenSecret in: query required: false schema: type: string description: Whether to include the token secret in the response. Defaults to false. Token storage must be supported and enabled by the connector to return the token secret. responses: '200': description: Returns the user's social identities, enterprise SSO identities and associated token secret. content: application/json: schema: type: object required: - socialIdentities - ssoIdentities properties: socialIdentities: type: array items: type: object required: - identity - target properties: identity: type: object required: - userId properties: userId: type: string details: type: object description: arbitrary tokenSecret: type: object required: - tenantId - id - userId - type - metadata - createdAt - updatedAt - connectorId - identityId - target properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 userId: type: string minLength: 1 maxLength: 21 type: type: string format: '"federated_token_set"' metadata: type: object required: - hasRefreshToken properties: scope: type: string expiresAt: type: number tokenType: type: string hasRefreshToken: type: boolean createdAt: type: number updatedAt: type: number connectorId: type: string identityId: type: string target: type: string target: type: string description: The user's social identities. ssoIdentities: type: array items: type: object required: - ssoIdentity - ssoConnectorId properties: ssoIdentity: 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 tokenSecret: type: object required: - tenantId - id - userId - type - metadata - createdAt - updatedAt - ssoConnectorId - issuer - identityId properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 userId: type: string minLength: 1 maxLength: 21 type: type: string format: '"federated_token_set"' metadata: type: object required: - hasRefreshToken properties: scope: type: string expiresAt: type: number tokenType: type: string hasRefreshToken: type: boolean createdAt: type: number updatedAt: type: number ssoConnectorId: type: string issuer: type: string identityId: type: string ssoConnectorId: type: string description: The user's enterprise SSO identities. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: User not found. summary: Retrieve social identities, enterprise SSO identities and associated token secret (if token storage is enabled) for a user. description: This API retrieves all identities (social and enterprise SSO) for a user, along with their associated token set records from the Logto Secret Vault. The token sets will only be available if token storage is enabled for the corresponding identity connector. /api/users/{userId}/sessions: get: operationId: ListUserSessions tags: - Users parameters: - $ref: '#/components/parameters/userId' responses: '200': description: Return a list of non-expired sessions of the user. content: application/json: schema: type: object required: - sessions properties: sessions: type: array items: type: object required: - payload - lastSubmission - clientId - accountId - expiresAt properties: payload: type: object required: - exp - iat - jti - uid - kind - loginTs - accountId properties: exp: type: number iat: type: number jti: type: string uid: type: string kind: type: string format: '"Session"' loginTs: type: number accountId: type: string authorizations: type: object additionalProperties: type: object properties: sid: type: string grantId: type: string persistsLogout: type: boolean lastSubmission: type: object required: - interactionEvent - userId - verificationRecords properties: interactionEvent: type: string enum: - SignIn - Register - ForgotPassword userId: type: string verificationRecords: type: array items: oneOf: - type: object required: - id - type - identifier - verified properties: id: type: string type: type: string format: '"Password"' identifier: type: object required: - type - value properties: type: oneOf: - type: string enum: - username - email - phone - type: string enum: - userId value: type: string verified: type: boolean - type: object required: - id - templateType - verified - type - identifier properties: id: type: string templateType: type: string enum: - SignIn - Register - ForgotPassword - OrganizationInvitation - Generic - UserPermissionValidation - BindNewIdentifier - MfaVerification - BindMfa verified: type: boolean type: type: string format: '"EmailVerificationCode"' identifier: type: object required: - type - value properties: type: type: string format: '"email"' value: type: string - type: object required: - id - templateType - verified - type - identifier properties: id: type: string templateType: type: string enum: - SignIn - Register - ForgotPassword - OrganizationInvitation - Generic - UserPermissionValidation - BindNewIdentifier - MfaVerification - BindMfa verified: type: boolean type: type: string format: '"PhoneVerificationCode"' identifier: type: object required: - type - value properties: type: type: string format: '"phone"' value: type: string - type: object required: - id - templateType - verified - type - identifier properties: id: type: string templateType: type: string enum: - SignIn - Register - ForgotPassword - OrganizationInvitation - Generic - UserPermissionValidation - BindNewIdentifier - MfaVerification - BindMfa verified: type: boolean type: type: string format: '"MfaEmailVerificationCode"' identifier: type: object required: - type - value properties: type: type: string format: '"email"' value: type: string - type: object required: - id - templateType - verified - type - identifier properties: id: type: string templateType: type: string enum: - SignIn - Register - ForgotPassword - OrganizationInvitation - Generic - UserPermissionValidation - BindNewIdentifier - MfaVerification - BindMfa verified: type: boolean type: type: string format: '"MfaPhoneVerificationCode"' identifier: type: object required: - type - value properties: type: type: string format: '"phone"' value: type: string - type: object required: - id - connectorId - type properties: id: type: string connectorId: type: string type: type: string format: '"Social"' socialUserInfo: type: object required: - id properties: id: type: string email: type: string phone: type: string name: type: string avatar: type: string rawData: type: object oneOf: - type: object description: arbitrary JSON object - type: array items: oneOf: - type: string - type: number - type: boolean - type: string nullable: true description: null value - type: object description: arbitrary JSON object - type: string - type: number - type: boolean nullable: true - type: object required: - id - connectorId - type properties: id: type: string connectorId: type: string type: type: string format: '"EnterpriseSso"' enterpriseSsoUserInfo: type: object required: - id properties: id: type: string email: type: string phone: type: string name: type: string avatar: type: string rawData: type: object oneOf: - type: object description: arbitrary JSON object - type: array items: oneOf: - type: string - type: number - type: boolean - type: string nullable: true description: null value - type: object description: arbitrary JSON object - type: string - type: number - type: boolean nullable: true issuer: type: string - type: object required: - id - type - userId - verified properties: id: type: string type: type: string format: '"Totp"' userId: type: string verified: type: boolean - type: object required: - id - type - userId properties: id: type: string type: type: string format: '"BackupCode"' userId: type: string code: type: string - type: object required: - id - verified - type - userId properties: id: type: string verified: type: boolean registrationRpId: type: string type: type: string format: '"WebAuthn"' userId: type: string - type: object required: - id - verified - type properties: id: type: string verified: type: boolean registrationRpId: type: string type: type: string format: '"SignInPasskey"' userId: type: string - type: object required: - id - type - verified - identifier properties: id: type: string type: type: string format: '"OneTimeToken"' verified: type: boolean identifier: type: object required: - type - value properties: type: type: string format: '"email"' value: type: string oneTimeTokenContext: type: object properties: jitOrganizationIds: type: array items: type: string - type: object required: - id - type - identifier properties: id: type: string type: type: string format: '"NewPasswordIdentity"' identifier: type: object required: - type - value properties: type: type: string enum: - username - email - phone value: type: string signInContext: type: object additionalProperties: type: string nullable: true clientId: type: string nullable: true accountId: type: string nullable: true expiresAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '500': description: Internal Server Error summary: Get user active sessions description: Retrieve all non-expired sessions for the user, including session metadata and interaction details when available. /api/users/{userId}/sessions/{sessionId}: get: operationId: GetUserSession tags: - Users parameters: - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/sessionId' responses: '200': description: Return a non-expired session of the user. content: application/json: schema: type: object required: - payload - lastSubmission - clientId - accountId - expiresAt properties: payload: type: object required: - exp - iat - jti - uid - kind - loginTs - accountId properties: exp: type: number iat: type: number jti: type: string uid: type: string kind: type: string format: '"Session"' loginTs: type: number accountId: type: string authorizations: type: object additionalProperties: type: object properties: sid: type: string grantId: type: string persistsLogout: type: boolean lastSubmission: type: object required: - interactionEvent - userId - verificationRecords properties: interactionEvent: type: string enum: - SignIn - Register - ForgotPassword userId: type: string verificationRecords: type: array items: oneOf: - type: object required: - id - type - identifier - verified properties: id: type: string type: type: string format: '"Password"' identifier: type: object required: - type - value properties: type: oneOf: - type: string enum: - username - email - phone - type: string enum: - userId value: type: string verified: type: boolean - type: object required: - id - templateType - verified - type - identifier properties: id: type: string templateType: type: string enum: - SignIn - Register - ForgotPassword - OrganizationInvitation - Generic - UserPermissionValidation - BindNewIdentifier - MfaVerification - BindMfa verified: type: boolean type: type: string format: '"EmailVerificationCode"' identifier: type: object required: - type - value properties: type: type: string format: '"email"' value: type: string - type: object required: - id - templateType - verified - type - identifier properties: id: type: string templateType: type: string enum: - SignIn - Register - ForgotPassword - OrganizationInvitation - Generic - UserPermissionValidation - BindNewIdentifier - MfaVerification - BindMfa verified: type: boolean type: type: string format: '"PhoneVerificationCode"' identifier: type: object required: - type - value properties: type: type: string format: '"phone"' value: type: string - type: object required: - id - templateType - verified - type - identifier properties: id: type: string templateType: type: string enum: - SignIn - Register - ForgotPassword - OrganizationInvitation - Generic - UserPermissionValidation - BindNewIdentifier - MfaVerification - BindMfa verified: type: boolean type: type: string format: '"MfaEmailVerificationCode"' identifier: type: object required: - type - value properties: type: type: string format: '"email"' value: type: string - type: object required: - id - templateType - verified - type - identifier properties: id: type: string templateType: type: string enum: - SignIn - Register - ForgotPassword - OrganizationInvitation - Generic - UserPermissionValidation - BindNewIdentifier - MfaVerification - BindMfa verified: type: boolean type: type: string format: '"MfaPhoneVerificationCode"' identifier: type: object required: - type - value properties: type: type: string format: '"phone"' value: type: string - type: object required: - id - connectorId - type properties: id: type: string connectorId: type: string type: type: string format: '"Social"' socialUserInfo: type: object required: - id properties: id: type: string email: type: string phone: type: string name: type: string avatar: type: string rawData: type: object oneOf: - type: object description: arbitrary JSON object - type: array items: oneOf: - type: string - type: number - type: boolean - type: string nullable: true description: null value - type: object description: arbitrary JSON object - type: string - type: number - type: boolean nullable: true - type: object required: - id - connectorId - type properties: id: type: string connectorId: type: string type: type: string format: '"EnterpriseSso"' enterpriseSsoUserInfo: type: object required: - id properties: id: type: string email: type: string phone: type: string name: type: string avatar: type: string rawData: type: object oneOf: - type: object description: arbitrary JSON object - type: array items: oneOf: - type: string - type: number - type: boolean - type: string nullable: true description: null value - type: object description: arbitrary JSON object - type: string - type: number - type: boolean nullable: true issuer: type: string - type: object required: - id - type - userId - verified properties: id: type: string type: type: string format: '"Totp"' userId: type: string verified: type: boolean - type: object required: - id - type - userId properties: id: type: string type: type: string format: '"BackupCode"' userId: type: string code: type: string - type: object required: - id - verified - type - userId properties: id: type: string verified: type: boolean registrationRpId: type: string type: type: string format: '"WebAuthn"' userId: type: string - type: object required: - id - verified - type properties: id: type: string verified: type: boolean registrationRpId: type: string type: type: string format: '"SignInPasskey"' userId: type: string - type: object required: - id - type - verified - identifier properties: id: type: string type: type: string format: '"OneTimeToken"' verified: type: boolean identifier: type: object required: - type - value properties: type: type: string format: '"email"' value: type: string oneTimeTokenContext: type: object properties: jitOrganizationIds: type: array items: type: string - type: object required: - id - type - identifier properties: id: type: string type: type: string format: '"NewPasswordIdentity"' identifier: type: object required: - type - value properties: type: type: string enum: - username - email - phone value: type: string signInContext: type: object additionalProperties: type: string nullable: true clientId: type: string nullable: true accountId: type: string nullable: true expiresAt: type: number '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error summary: Get user active session description: Retrieve a non-expired session for the user by session ID, including session metadata and interaction details when available. delete: operationId: DeleteUserSession tags: - Users parameters: - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/sessionId' - name: revokeGrantsTarget in: query required: false schema: type: string enum: - all - firstParty description: Optional target for revoking associated grants and tokens. 'all' revokes grants for every application authorized by this session. 'firstParty' revokes only first-party app grants; third-party app grants remain active. If omitted, grants remain active when the session authorizations include offline_access; otherwise they are revoked. responses: '204': description: Session revoked successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error summary: Revoke a user session description: Revoke a specific user session by its ID, optionally revoking associated target grants and tokens. components: parameters: ssoConnectorId: in: path description: The unique identifier of the sso connector. required: true schema: type: string name: ssoConnectorId roleId: in: path description: The unique identifier of the role. required: true schema: type: string name: roleId grantId: in: path description: The unique identifier of the grant. required: true schema: type: string name: grantId verificationId: in: path description: The unique identifier of the verification. required: true schema: type: string name: verificationId sessionId: in: path description: The unique identifier of the session. required: true schema: type: string name: sessionId userId: in: path description: The unique identifier of the user. required: true schema: type: string name: userId securitySchemes: OAuth2: type: oauth2 description: "Logto Management API is a comprehensive set of REST APIs that gives you the full control over Logto to suit your product needs and tech stack. To see the full guide on Management API interactions, visit [Interact with Management API](https://docs.logto.io/docs/recipes/interact-with-management-api/).\n\n### Get started\n\nThe API follows the same authentication principles as other API resources in Logto, with some slight differences. To use Logto Management API:\n\n1. A machine-to-machine (M2M) application needs to be created.\n2. A machine-to-machine (M2M) role with Management API permission `all` needs to be assigned to the application.\n\nOnce you have them set up, you can use the `client_credentials` grant type to fetch an access token and use it to authenticate your requests to the Logto Management API.\n\n### Fetch an access token\n\nTo fetch an access token, you need to make a `POST` request to the `/oidc/token` endpoint of your Logto tenant.\n\nFor Logto Cloud users, the base URL is your Logto endpoint, i.e. `https://[tenant-id].logto.app`. The tenant ID can be found in the following places:\n\n- The first path segment of the URL when you are signed in to Logto Cloud. For example, if the URL is `https://cloud.logto.io/foo/get-started`, the tenant ID is `foo`.\n- In the \"Settings\" tab of Logto Cloud.\n\nThe request should follow the OAuth 2.0 [client credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) grant type. Here is a non-normative example of how to fetch an access token:\n\n```bash\ncurl --location \\\n --request POST 'https://[tenant-id].logto.app/oidc/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'client_id=[app-id]' \\\n --data-urlencode 'client_secret=[app-secret]' \\\n --data-urlencode 'resource=https://[tenant-id].logto.app/api' \\\n --data-urlencode 'scope=all'\n```\n\nReplace `[tenant-id]`, `[app-id]`, and `[app-secret]` with your Logto tenant ID, application ID, and application secret, respectively.\n\nThe response will be like:\n\n```json\n{\n \"access_token\": \"eyJhbG...2g\", // Use this value for accessing the Logto Management API\n \"expires_in\": 3600, // Token expiration in seconds\n \"token_type\": \"Bearer\", // Token type for your request when using the access token\n \"scope\": \"all\" // Scope `all` for Logto Management API\n}\n```\n\n### Use the access token\n\nOnce you have the access token, you can use it to authenticate your requests to the Logto Management API. The access token should be included in the `Authorization` header of your requests with the `Bearer` authentication scheme.\n\nHere is an example of how to list the first page of users in your Logto tenant:\n\n```bash\ncurl --location \\\n --request GET 'https://[tenant-id].logto.app/api/users' \\\n --header 'Authorization: Bearer eyJhbG...2g'\n```\n\nReplace `[tenant-id]` with your Logto tenant ID and `eyJhbG...2g` with the access token you fetched earlier." flows: clientCredentials: tokenUrl: /oidc/token scopes: all: All scopes