openapi: 3.0.1 info: title: Logto API references Account center My account 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: My account description: Account routes provide functionality for managing user profile for the end user to interact directly with access tokens. paths: /api/my-account: get: operationId: GetProfile tags: - My account parameters: [] responses: '200': description: The profile was retrieved successfully. content: application/json: schema: type: object 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 '401': description: Unauthorized '403': description: Forbidden summary: Get profile description: Get profile for the user. patch: operationId: UpdateProfile tags: - My account parameters: [] requestBody: required: true content: application/json: schema: type: object properties: name: type: string nullable: true description: The new name for the user. avatar: type: string format: url nullable: true description: The new avatar for the user, must be a URL. username: type: string format: regex pattern: /^[A-Z_a-z]\w*$/ nullable: true description: The new username for the user, must be a valid username and unique. customData: type: object description: The new custom data for the user. This will completely replace the existing customData. Requires CustomData scope. responses: '200': description: The profile was updated successfully. content: application/json: schema: type: object 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: The request body is invalid. '401': description: Permission denied, the verification record is invalid. '403': description: Forbidden '422': description: The username is already in use. summary: Update profile description: Update profile for the user, only the fields that are passed in will be updated. Updating or deleting username requires a logto-verification-id header for checking sensitive permissions. Removing any sign-in identifier, including username, is rejected if it would remove the user's last identifier. /api/my-account/profile: patch: operationId: UpdateOtherProfile tags: - My account parameters: [] requestBody: required: true content: application/json: schema: type: object properties: familyName: type: string description: The new family name for the user. givenName: type: string description: The new given name for the user. middleName: type: string description: The new middle name for the user. nickname: type: string description: The new nickname for the user. preferredUsername: type: string description: The new preferred username for the user. profile: type: string description: The new profile for the user. website: type: string description: The new website for the user. gender: type: string description: The new gender for the user. birthdate: type: string description: The new birthdate for the user. zoneinfo: type: string description: The new zoneinfo for the user. locale: type: string description: The new locale for the user. address: type: object properties: formatted: type: string streetAddress: type: string locality: type: string region: type: string postalCode: type: string country: type: string description: The new address for the user. responses: '200': description: The profile was updated successfully. 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 summary: Update other profile description: Update other profile for the user, only the fields that are passed in will be updated, to update the address, the user must have the address scope. /api/my-account/password: post: operationId: UpdatePassword tags: - My account parameters: [] requestBody: required: true content: application/json: schema: type: object required: - password properties: password: type: string minLength: 1 description: The new password for the user. responses: '204': description: The password was updated successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Permission denied, the verification record is invalid. '422': description: Unprocessable Content summary: Update password description: Update password for the user, a logto-verification-id in header is required for checking sensitive permissions. /api/my-account/mfa-settings: get: operationId: GetMfaSettings tags: - My account parameters: [] responses: '200': description: The MFA settings were retrieved successfully. content: application/json: schema: type: object required: - skipMfaOnSignIn properties: skipMfaOnSignIn: type: boolean '400': description: Bad Request '401': description: Permission denied, insufficient scope or MFA field not enabled. '403': description: Forbidden summary: Get MFA settings description: Get MFA settings for the user. This endpoint requires the Identities scope. Returns current MFA configuration preferences. patch: operationId: UpdateMfaSettings tags: - My account parameters: [] requestBody: required: true content: application/json: schema: type: object required: - skipMfaOnSignIn properties: skipMfaOnSignIn: type: boolean responses: '200': description: The MFA settings were updated successfully. content: application/json: schema: type: object required: - skipMfaOnSignIn properties: skipMfaOnSignIn: type: boolean '400': description: The request body is invalid. '401': description: Permission denied, identity verification is required or insufficient scope. '403': description: Forbidden summary: Update MFA settings description: Update MFA settings for the user. This endpoint requires identity verification and the Identities scope. Controls whether MFA verification is required during sign-in when the user has MFA configured. /api/my-account/logto-configs: get: operationId: GetLogtoConfig tags: - My account parameters: [] responses: '200': description: The exposed logto config fields were retrieved 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: MFA is not available in the account center. '401': description: Permission denied due to insufficient scope. '403': description: Forbidden summary: Get logto config description: Retrieve the exposed portion of the current user's logto config. This includes MFA states (enabled, skipped, skipMfaOnSignIn) and passkey sign-in binding states (skipped). Passkey is a WebAuthn MFA factor and shares the same account center field access control as MFA. patch: operationId: UpdateLogtoConfig tags: - My account parameters: [] 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: The request body is invalid. '401': description: Permission denied due to insufficient scope. '403': description: Forbidden summary: Update logto config description: Update the exposed portion of the current user's logto config. Supports updating MFA states (enabled, skipped, skipMfaOnSignIn) and passkey sign-in binding states (skipped). Passkey is a WebAuthn MFA factor and shares the same account center field access control as MFA. /api/my-account/identities/{target}/access-token: get: operationId: GetSocialIdentityAccessToken tags: - My account parameters: - name: target in: path required: true schema: type: string minLength: 1 responses: '200': description: The access token was retrieved successfully. content: application/json: schema: type: object required: - access_token properties: access_token: type: string scope: type: string token_type: type: string expires_in: oneOf: - type: number - type: string '400': description: Bad Request '401': description: Permission denied, the access_token is expired and the offline_access scope is not granted or expired. '403': description: Forbidden '404': description: The social identity does not exist or the access token is not available. '422': description: Unprocessable Content summary: Retrieve the access token issued by a third-party social provider description: "This API retrieves the access token issued by a third-party social provider for a given social target. \nAccess is only available if token storage is enabled for the corresponding social connector.\nWhen a user authenticates through a social provider, Logto automatically stores the provider’s tokens in an encrypted form.\nYou can use this API to securely retrieve the stored access token and use it to access third-party APIs on behalf of the user." put: operationId: UpdateSocialIdentityAccessTokenByVerificationId tags: - My account parameters: - name: target in: path required: true schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: type: object required: - verificationRecordId properties: verificationRecordId: type: string minLength: 1 responses: '200': description: The token storage was updated successfully. The new access token is returned in the response body. content: application/json: schema: type: object required: - access_token properties: access_token: type: string scope: type: string token_type: type: string expires_in: oneOf: - type: number - type: string '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: The verification record is invalid; the social identity does not exist; or the access token is not available. summary: Update the access token for a social identity by verification ID description: "This API updates the token storage for a social identity by a given social verification ID. \nIt is used to fetch a new access token from the social provider and store it securely in Logto." /api/my-account/sso-identities/{connectorId}/access-token: get: operationId: GetEnterpriseSsoIdentityAccessToken tags: - My account parameters: - $ref: '#/components/parameters/connectorId' responses: '200': description: The access token was retrieved successfully. content: application/json: schema: type: object required: - access_token properties: access_token: type: string scope: type: string token_type: type: string expires_in: oneOf: - type: number - type: string '400': description: Bad Request '401': description: Permission denied, the access_token is expired and the offline_access scope is not granted or expired. '403': description: Forbidden '404': description: The SSO connector does not exist or the access token is not available. summary: Retrieve the access token issued by a third-party enterprise SSO provider description: "This API retrieves the access token issued by a third-party enterprise SSO provider for a given SSO connector ID. \nAccess is only available if token storage is enabled for the corresponding connector.\nWhen a user authenticates through a SSO provider, Logto automatically stores the provider’s tokens in an encrypted form.\nYou can use this API to securely retrieve the stored access token and use it to access third-party APIs on behalf of the user." /api/my-account/primary-email: post: operationId: UpdatePrimaryEmail tags: - My account parameters: [] requestBody: required: true content: application/json: schema: type: object required: - email - newIdentifierVerificationRecordId properties: email: type: string format: regex pattern: /^\S+@\S+\.\S+$/ description: The new email for the user. newIdentifierVerificationRecordId: type: string description: The identifier verification record ID for the new email ownership verification. responses: '204': description: The primary email was updated successfully. '400': description: The new verification record is invalid. '401': description: Unauthorized '403': description: Permission denied, the verification record is invalid. '422': description: Unprocessable Content summary: Update primary email description: Update primary email for the user, a logto-verification-id in header is required for checking sensitive permissions, and a new identifier verification record is required for the new email ownership verification. delete: operationId: DeletePrimaryEmail tags: - My account parameters: [] responses: '204': description: The primary email was deleted successfully. '400': description: The request would remove the user's last identifier. '401': description: Permission denied, the verification record is invalid. '403': description: Forbidden summary: Delete primary email description: Delete primary email for the user, a logto-verification-id header is required for checking sensitive permissions. The request is rejected if it would remove the user's last identifier. /api/my-account/primary-phone: post: operationId: UpdatePrimaryPhone tags: - My account parameters: [] requestBody: required: true content: application/json: schema: type: object required: - phone - newIdentifierVerificationRecordId properties: phone: type: string format: regex pattern: /^\d+$/ description: The new phone for the user. newIdentifierVerificationRecordId: type: string description: The identifier verification record ID for the new phone ownership verification. responses: '204': description: The primary phone was updated successfully. '400': description: The new verification record is invalid. '401': description: Unauthorized '403': description: Permission denied, the verification record is invalid. '422': description: Unprocessable Content summary: Update primary phone description: Update primary phone for the user, a logto-verification-id in header is required for checking sensitive permissions, and a new identifier verification record is required for the new phone ownership verification. delete: operationId: DeletePrimaryPhone tags: - My account parameters: [] responses: '204': description: The primary phone was deleted successfully. '400': description: The request would remove the user's last identifier. '401': description: Permission denied, the verification record is invalid. '403': description: Forbidden summary: Delete primary phone description: Delete primary phone for the user, a logto-verification-id header is required for checking sensitive permissions. The request is rejected if it would remove the user's last identifier. /api/my-account/identities: post: operationId: AddUserIdentities tags: - My account parameters: [] requestBody: required: true content: application/json: schema: type: object required: - newIdentifierVerificationRecordId properties: newIdentifierVerificationRecordId: type: string description: The identifier verification record ID for the new social identity ownership verification. responses: '204': description: The identity was added successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Add a user identity description: Add an identity (social identity) to the user, a logto-verification-id in header is required for checking sensitive permissions, and a verification record for the social identity is required. /api/my-account/identities/{target}: delete: operationId: DeleteIdentity tags: - My account parameters: - name: target in: path required: true schema: type: string responses: '204': description: The identity was deleted successfully. '400': description: The request would remove the user's last identifier. '401': description: Permission denied, the verification record is invalid. '403': description: Forbidden '404': description: The identity does not exist. summary: Delete a user identity description: Delete an identity (social identity) from the user, a logto-verification-id in header is required for checking sensitive permissions. The request is rejected if it would remove the user's last identifier. /api/my-account/mfa-verifications: get: operationId: GetMfaVerifications tags: - My account parameters: [] responses: '200': description: The MFA verifications were retrieved successfully. 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 summary: Get MFA verifications description: Get MFA verifications for the user. post: operationId: AddMfaVerification tags: - My account parameters: [] requestBody: required: true content: application/json: schema: oneOf: - type: object required: - type - newIdentifierVerificationRecordId properties: type: type: string format: '"WebAuthn"' newIdentifierVerificationRecordId: type: string name: type: string - type: object required: - type - secret properties: type: type: string format: '"Totp"' secret: type: string code: type: string - type: object required: - type - codes properties: type: type: string format: '"BackupCode"' codes: type: array items: type: string - type: object properties: type: type: string enum: - WebAuthn description: The type of the MFA verification. newIdentifierVerificationRecordId: type: string description: The identifier verification record ID for the new WebAuthn registration verification. name: type: string description: The name of the MFA verification, if not provided, the name will be generated from user agent. required: - type - newIdentifierVerificationRecordId - type: object properties: type: type: string enum: - TOTP description: The type of the MFA verification, for TOTP, one user can only bind one TOTP factor. secret: type: string description: The TOTP secret for the MFA verification. Use the generate endpoint to create a secret, and verify the generated code with the user before binding to make sure the user has setup the secret in their authenticator app. code: type: string description: Optional. The TOTP code generated by the secret to verify the binding. required: - type - secret - type: object properties: type: type: string enum: - BackupCode description: The type of the MFA verification, for backup codes, one user can only bind one set of backup codes and requires at least one other MFA factor. codes: type: array items: type: string description: Array of backup codes. Use the generate endpoint to create codes. required: - type - codes responses: '204': description: No Content '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden '422': description: Unprocessable Content summary: Add a MFA verification description: Add a MFA verification to the user, a logto-verification-id in header is required for checking sensitive permissions. /api/my-account/mfa-verifications/totp: put: operationId: CreateOrReplaceTotpMfaVerification tags: - My account parameters: [] requestBody: required: true content: application/json: schema: type: object required: - secret - code properties: secret: type: string description: The TOTP secret for the authenticator app. code: type: string description: The TOTP code generated from the secret to confirm the binding. responses: '204': description: The authenticator app was created or replaced successfully. '400': description: The provided secret or TOTP code is invalid. '401': description: Permission denied, identity verification is required or insufficient scope. '403': description: Forbidden summary: Create or replace the authenticator app description: Create or replace the user's TOTP MFA verification with a new authenticator app binding. If the user already has a TOTP verification, it will be replaced; otherwise, a new one will be created. Requires a logto-verification-id header for sensitive permission checks, a valid TOTP secret, and a valid TOTP code generated from the secret. /api/my-account/mfa-verifications/totp-secret/generate: post: operationId: GenerateTotpSecret tags: - My account parameters: [] responses: '200': description: The TOTP secret was generated successfully. content: application/json: {} '401': description: Unauthorized '403': description: Forbidden summary: Generate a TOTP secret description: Generate a TOTP secret for the user. /api/my-account/mfa-verifications/backup-codes/generate: post: operationId: GenerateMyAccountBackupCodes tags: - My account parameters: [] responses: '200': description: The backup codes were generated successfully. content: application/json: {} '401': description: Unauthorized '403': description: Forbidden summary: Generate backup codes description: Generate backup codes for the user. /api/my-account/mfa-verifications/backup-codes: get: operationId: GetBackupCodes tags: - My account parameters: [] responses: '200': description: The backup codes were retrieved successfully. content: application/json: {} '401': description: Unauthorized or identity verification required. '403': description: Forbidden '404': description: No backup codes found for the user. summary: Get backup codes description: Get all backup codes for the user with their usage status. Requires identity verification. /api/my-account/mfa-verifications/{verificationId}/name: patch: operationId: UpdateMfaVerificationName tags: - My account parameters: - $ref: '#/components/parameters/verificationId' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: The name of the MFA verification. responses: '200': description: The MFA verification name was updated successfully. content: application/json: {} '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Update a MFA verification name description: Update a MFA verification name, a logto-verification-id in header is required for checking sensitive permissions. Only WebAuthn is supported for now. /api/my-account/mfa-verifications/{verificationId}: delete: operationId: DeleteMfaVerification tags: - My account parameters: - $ref: '#/components/parameters/verificationId' responses: '204': description: The MFA verification was deleted successfully. '400': description: Bad Request '401': description: Unauthorized '403': description: Forbidden summary: Delete an MFA verification description: Delete an MFA verification, a logto-verification-id in header is required for checking sensitive permissions. /api/my-account/sessions: get: operationId: GetSessions tags: - My account parameters: [] 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: Permission denied, the verification record is invalid or the session does not have the required scope to access session details. '403': description: Forbidden '500': description: Internal Server Error summary: Get all active sessions description: Retrieve all non-expired sessions for the user, including session metadata and interaction details when available. A logto-verification-id in header is required for checking sensitive session details. /api/my-account/sessions/{sessionId}: delete: operationId: DeleteSessionById tags: - My account parameters: - $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: The session was revoked successfully. '400': description: The field is not editable. '401': description: Permission denied, the verification record is invalid or the session does not have the required scope to revoke sessions. '403': description: Forbidden '404': description: The session does not exist. '500': description: Internal Server Error summary: Revoke a session by ID description: Revoke a specific user session by its ID, optionally revoking target associated grants and tokens. A logto-verification-id in header is required for revoking sessions. /api/my-account/grants: get: operationId: GetGrants tags: - My account parameters: - name: appType in: query required: false schema: type: string enum: - firstParty - thirdParty description: Optional application type filter. Use 'firstParty' to return grants from first-party applications only, or 'thirdParty' for third-party applications only. responses: '200': description: Return a list of active application grants of the user. 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: Permission denied, the verification record is invalid or the session does not have the required scope to access grant details. '403': description: Forbidden '500': description: Internal Server Error summary: Get all active grants description: Retrieve all active application grants for the user. A logto-verification-id in header is required for checking grant details. /api/my-account/grants/{grantId}: delete: operationId: DeleteGrantById tags: - My account parameters: - $ref: '#/components/parameters/grantId' responses: '204': description: The grant was revoked successfully. '400': description: The field is not editable. '401': description: Permission denied, the verification record is invalid or the session does not have the required scope to revoke grants. '403': description: Forbidden '404': description: The grant does not exist. '500': description: Internal Server Error summary: Revoke a grant by ID description: Revoke a specific user application grant by grant ID and remove the related session authorization. A logto-verification-id in header is required for revoking grants. components: parameters: verificationId: in: path description: The unique identifier of the verification. required: true schema: type: string name: verificationId connectorId: in: path description: The unique identifier of the connector. required: true schema: type: string name: connectorId grantId: in: path description: The unique identifier of the grant. required: true schema: type: string name: grantId sessionId: in: path description: The unique identifier of the session. required: true schema: type: string name: sessionId 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