openapi: 3.0.1 info: title: Logto API references Account center Well-known 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: Well-known description: Well-Known routes provide information and resources that can be discovered by clients without the need for authentication. paths: /api/.well-known/sign-in-exp: get: operationId: GetSignInExperienceConfig tags: - Well-known parameters: - name: organizationId in: query required: false schema: type: string - name: appId in: query required: false schema: type: string responses: '200': description: The full sign-in experience configuration. content: application/json: schema: type: object required: - tenantId - id - color - branding - hideLogtoBranding - languageInfo - termsOfUseUrl - privacyPolicyUrl - agreeToTermsPolicy - signIn - signUp - socialSignIn - socialSignInConnectorTargets - signInMode - customCss - customContent - customUiAssets - passwordPolicy - mfa - adaptiveMfa - singleSignOnEnabled - supportEmail - supportWebsiteUrl - unknownSessionRedirectUrl - captchaPolicy - sentinelPolicy - emailBlocklistPolicy - passkeySignIn - signUpProfileFields - socialConnectors - ssoConnectors - forgotPassword - isDevelopmentTenant - customProfileFields properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 color: type: object required: - primaryColor - isDarkModeEnabled - darkPrimaryColor 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 hideLogtoBranding: type: boolean languageInfo: type: object required: - autoDetect - fallbackLanguage properties: autoDetect: type: boolean fallbackLanguage: type: string enum: - af-ZA - am-ET - ar - ar-AR - as-IN - az-AZ - be-BY - bg-BG - bn-IN - br-FR - bs-BA - ca-ES - cb-IQ - co-FR - cs - cs-CZ - cx-PH - cy-GB - da-DK - de - de-DE - el-GR - en - en-GB - en-US - eo-EO - es - es-ES - es-419 - et-EE - eu-ES - fa-IR - ff-NG - fi - fi-FI - fo-FO - fr - fr-CA - fr-FR - fy-NL - ga-IE - gl-ES - gn-PY - gu-IN - ha-NG - he-IL - hi-IN - hr-HR - ht-HT - hu-HU - hy-AM - id-ID - ik-US - is-IS - it - it-IT - iu-CA - ja - ja-JP - ja-KS - jv-ID - ka-GE - kk-KZ - km-KH - kn-IN - ko - ko-KR - ku-TR - ky-KG - lo-LA - lt-LT - lv-LV - mg-MG - mk-MK - ml-IN - mn-MN - mr-IN - ms-MY - mt-MT - my-MM - nb-NO - ne-NP - nl - nl-BE - nl-NL - nn-NO - or-IN - pa-IN - pl-PL - ps-AF - pt - pt-BR - pt-PT - ro-RO - ru - ru-RU - rw-RW - sc-IT - si-LK - sk-SK - sl-SI - sn-ZW - sq-AL - sr-RS - sv - sv-SE - sw-KE - sy-SY - sz-PL - ta-IN - te-IN - tg-TJ - th - th-TH - tl-PH - tr - tr-TR - tt-RU - tz-MA - uk-UA - ur-PK - uz-UZ - vi-VN - zh - zh-CN - zh-HK - zh-MO - zh-TW - zz-TR termsOfUseUrl: type: string maxLength: 2048 nullable: true privacyPolicyUrl: type: string maxLength: 2048 nullable: true agreeToTermsPolicy: type: string enum: - Automatic - ManualRegistrationOnly - Manual signIn: type: object required: - methods properties: methods: type: array items: type: object required: - identifier - password - verificationCode - isPasswordPrimary properties: identifier: type: string enum: - username - email - phone password: type: boolean verificationCode: type: boolean isPasswordPrimary: type: boolean signUp: type: object required: - identifiers - password - verify properties: identifiers: type: array items: type: string enum: - username - email - phone password: type: boolean verify: type: boolean secondaryIdentifiers: type: array items: type: object required: - identifier properties: identifier: oneOf: - type: string enum: - username - email - phone - type: string enum: - emailOrPhone verify: type: boolean socialSignIn: type: object properties: automaticAccountLinking: type: boolean skipRequiredIdentifiers: type: boolean socialSignInConnectorTargets: type: array items: type: string signInMode: type: string enum: - SignIn - Register - SignInAndRegister customCss: type: string nullable: true customContent: type: object additionalProperties: type: string customUiAssets: type: object required: - id - createdAt properties: id: type: string createdAt: type: number nullable: true passwordPolicy: type: object properties: length: default: {} type: object required: - min - max properties: min: default: 8 type: number max: default: 256 type: number characterTypes: default: {} type: object required: - min properties: min: default: 1 type: number rejects: default: {} type: object required: - pwned - repetitionAndSequence - userInfo - words properties: pwned: default: true type: boolean repetitionAndSequence: default: true type: boolean userInfo: default: true type: boolean words: default: [] type: array items: type: string mfa: type: object required: - factors - policy properties: factors: type: array items: type: string enum: - Totp - WebAuthn - BackupCode - EmailVerificationCode - PhoneVerificationCode policy: type: string enum: - UserControlled - Mandatory - PromptOnlyAtSignIn - PromptAtSignInAndSignUp - NoPrompt - PromptAtSignInAndSignUpMandatory - PromptOnlyAtSignInMandatory organizationRequiredMfaPolicy: type: string enum: - NoPrompt - Mandatory adaptiveMfa: type: object properties: enabled: type: boolean singleSignOnEnabled: type: boolean supportEmail: type: string nullable: true supportWebsiteUrl: type: string nullable: true unknownSessionRedirectUrl: type: string nullable: true captchaPolicy: type: object properties: enabled: type: boolean sentinelPolicy: type: object properties: maxAttempts: type: number lockoutDuration: type: number emailBlocklistPolicy: type: object properties: blockDisposableAddresses: type: boolean blockSubaddressing: type: boolean customBlocklist: type: array items: type: string passkeySignIn: type: object properties: enabled: type: boolean showPasskeyButton: type: boolean allowAutofill: type: boolean signUpProfileFields: type: array items: type: object required: - name properties: name: type: string nullable: true socialConnectors: type: array items: type: object required: - id - target - name - logo - logoDark - platform properties: id: type: string target: type: string name: type: object description: Validator function logo: type: string logoDark: type: string nullable: true fromEmail: type: string platform: type: string enum: - Native - Universal - Web nullable: true isStandard: type: boolean isTokenStorageSupported: type: boolean ssoConnectors: type: array items: type: object required: - id - connectorName - logo properties: id: type: string connectorName: type: string logo: type: string darkLogo: type: string forgotPassword: type: object required: - phone - email properties: phone: type: boolean email: type: boolean isDevelopmentTenant: type: boolean googleOneTap: type: object required: - clientId - connectorId properties: isEnabled: type: boolean autoSelect: type: boolean closeOnTapOutside: type: boolean itpSupport: type: boolean clientId: type: string connectorId: type: string captchaConfig: type: object required: - type - siteKey properties: type: type: string enum: - RecaptchaEnterprise - Turnstile siteKey: type: string domain: type: string mode: type: string enum: - invisible - checkbox customProfileFields: type: array items: type: object required: - tenantId - id - name - type - label - description - required - config - createdAt - sieOrder properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 128 type: type: string enum: - Text - Number - Date - Checkbox - Select - Url - Regex - Address - Fullname label: type: string maxLength: 128 description: type: string maxLength: 256 nullable: true required: type: boolean config: type: object properties: placeholder: type: string maxLength: 256 minLength: type: number maxLength: type: number minValue: type: number maxValue: type: number format: type: string maxLength: 128 customFormat: type: string maxLength: 128 options: type: array items: type: object required: - value properties: label: type: string value: type: string defaultValue: type: string parts: type: array items: type: object required: - enabled - name - type - required properties: enabled: type: boolean name: type: string type: type: string enum: - Text - Number - Date - Checkbox - Select - Url - Regex - Address - Fullname label: type: string minLength: 1 description: type: string required: type: boolean config: type: object properties: placeholder: type: string maxLength: 256 minLength: type: number maxLength: type: number minValue: type: number maxValue: type: number format: type: string maxLength: 128 customFormat: type: string maxLength: 128 options: type: array items: type: object required: - value properties: label: type: string value: type: string defaultValue: type: string createdAt: type: number sieOrder: type: number '400': description: Bad Request security: [] deprecated: true summary: Get full sign-in experience description: Get the full sign-in experience configuration. /api/.well-known/phrases: get: operationId: GetSignInExperiencePhrases tags: - Well-known parameters: - name: lng in: query required: false schema: type: string description: The language tag for localization. responses: '200': description: Localized phrases for the specified language. content: application/json: schema: type: object additionalProperties: oneOf: - type: string - type: object additionalProperties: example: {} '400': description: Bad Request security: [] summary: Get localized phrases description: Get localized phrases based on the specified language. /api/.well-known/experience: get: operationId: GetWellKnownExperience tags: - Well-known parameters: - name: organizationId in: query required: false schema: type: string - name: appId in: query required: false schema: type: string responses: '200': description: The full sign-in experience configuration. content: application/json: schema: type: object required: - tenantId - id - color - branding - hideLogtoBranding - languageInfo - termsOfUseUrl - privacyPolicyUrl - agreeToTermsPolicy - signIn - signUp - socialSignIn - socialSignInConnectorTargets - signInMode - customCss - customContent - customUiAssets - passwordPolicy - mfa - adaptiveMfa - singleSignOnEnabled - supportEmail - supportWebsiteUrl - unknownSessionRedirectUrl - captchaPolicy - sentinelPolicy - emailBlocklistPolicy - passkeySignIn - signUpProfileFields - socialConnectors - ssoConnectors - forgotPassword - isDevelopmentTenant - customProfileFields properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 color: type: object required: - primaryColor - isDarkModeEnabled - darkPrimaryColor 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 hideLogtoBranding: type: boolean languageInfo: type: object required: - autoDetect - fallbackLanguage properties: autoDetect: type: boolean fallbackLanguage: type: string enum: - af-ZA - am-ET - ar - ar-AR - as-IN - az-AZ - be-BY - bg-BG - bn-IN - br-FR - bs-BA - ca-ES - cb-IQ - co-FR - cs - cs-CZ - cx-PH - cy-GB - da-DK - de - de-DE - el-GR - en - en-GB - en-US - eo-EO - es - es-ES - es-419 - et-EE - eu-ES - fa-IR - ff-NG - fi - fi-FI - fo-FO - fr - fr-CA - fr-FR - fy-NL - ga-IE - gl-ES - gn-PY - gu-IN - ha-NG - he-IL - hi-IN - hr-HR - ht-HT - hu-HU - hy-AM - id-ID - ik-US - is-IS - it - it-IT - iu-CA - ja - ja-JP - ja-KS - jv-ID - ka-GE - kk-KZ - km-KH - kn-IN - ko - ko-KR - ku-TR - ky-KG - lo-LA - lt-LT - lv-LV - mg-MG - mk-MK - ml-IN - mn-MN - mr-IN - ms-MY - mt-MT - my-MM - nb-NO - ne-NP - nl - nl-BE - nl-NL - nn-NO - or-IN - pa-IN - pl-PL - ps-AF - pt - pt-BR - pt-PT - ro-RO - ru - ru-RU - rw-RW - sc-IT - si-LK - sk-SK - sl-SI - sn-ZW - sq-AL - sr-RS - sv - sv-SE - sw-KE - sy-SY - sz-PL - ta-IN - te-IN - tg-TJ - th - th-TH - tl-PH - tr - tr-TR - tt-RU - tz-MA - uk-UA - ur-PK - uz-UZ - vi-VN - zh - zh-CN - zh-HK - zh-MO - zh-TW - zz-TR termsOfUseUrl: type: string maxLength: 2048 nullable: true privacyPolicyUrl: type: string maxLength: 2048 nullable: true agreeToTermsPolicy: type: string enum: - Automatic - ManualRegistrationOnly - Manual signIn: type: object required: - methods properties: methods: type: array items: type: object required: - identifier - password - verificationCode - isPasswordPrimary properties: identifier: type: string enum: - username - email - phone password: type: boolean verificationCode: type: boolean isPasswordPrimary: type: boolean signUp: type: object required: - identifiers - password - verify properties: identifiers: type: array items: type: string enum: - username - email - phone password: type: boolean verify: type: boolean secondaryIdentifiers: type: array items: type: object required: - identifier properties: identifier: oneOf: - type: string enum: - username - email - phone - type: string enum: - emailOrPhone verify: type: boolean socialSignIn: type: object properties: automaticAccountLinking: type: boolean skipRequiredIdentifiers: type: boolean socialSignInConnectorTargets: type: array items: type: string signInMode: type: string enum: - SignIn - Register - SignInAndRegister customCss: type: string nullable: true customContent: type: object additionalProperties: type: string customUiAssets: type: object required: - id - createdAt properties: id: type: string createdAt: type: number nullable: true passwordPolicy: type: object properties: length: default: {} type: object required: - min - max properties: min: default: 8 type: number max: default: 256 type: number characterTypes: default: {} type: object required: - min properties: min: default: 1 type: number rejects: default: {} type: object required: - pwned - repetitionAndSequence - userInfo - words properties: pwned: default: true type: boolean repetitionAndSequence: default: true type: boolean userInfo: default: true type: boolean words: default: [] type: array items: type: string mfa: type: object required: - factors - policy properties: factors: type: array items: type: string enum: - Totp - WebAuthn - BackupCode - EmailVerificationCode - PhoneVerificationCode policy: type: string enum: - UserControlled - Mandatory - PromptOnlyAtSignIn - PromptAtSignInAndSignUp - NoPrompt - PromptAtSignInAndSignUpMandatory - PromptOnlyAtSignInMandatory organizationRequiredMfaPolicy: type: string enum: - NoPrompt - Mandatory adaptiveMfa: type: object properties: enabled: type: boolean singleSignOnEnabled: type: boolean supportEmail: type: string nullable: true supportWebsiteUrl: type: string nullable: true unknownSessionRedirectUrl: type: string nullable: true captchaPolicy: type: object properties: enabled: type: boolean sentinelPolicy: type: object properties: maxAttempts: type: number lockoutDuration: type: number emailBlocklistPolicy: type: object properties: blockDisposableAddresses: type: boolean blockSubaddressing: type: boolean customBlocklist: type: array items: type: string passkeySignIn: type: object properties: enabled: type: boolean showPasskeyButton: type: boolean allowAutofill: type: boolean signUpProfileFields: type: array items: type: object required: - name properties: name: type: string nullable: true socialConnectors: type: array items: type: object required: - id - target - name - logo - logoDark - platform properties: id: type: string target: type: string name: type: object description: Validator function logo: type: string logoDark: type: string nullable: true fromEmail: type: string platform: type: string enum: - Native - Universal - Web nullable: true isStandard: type: boolean isTokenStorageSupported: type: boolean ssoConnectors: type: array items: type: object required: - id - connectorName - logo properties: id: type: string connectorName: type: string logo: type: string darkLogo: type: string forgotPassword: type: object required: - phone - email properties: phone: type: boolean email: type: boolean isDevelopmentTenant: type: boolean googleOneTap: type: object required: - clientId - connectorId properties: isEnabled: type: boolean autoSelect: type: boolean closeOnTapOutside: type: boolean itpSupport: type: boolean clientId: type: string connectorId: type: string captchaConfig: type: object required: - type - siteKey properties: type: type: string enum: - RecaptchaEnterprise - Turnstile siteKey: type: string domain: type: string mode: type: string enum: - invisible - checkbox customProfileFields: type: array items: type: object required: - tenantId - id - name - type - label - description - required - config - createdAt - sieOrder properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 name: type: string minLength: 1 maxLength: 128 type: type: string enum: - Text - Number - Date - Checkbox - Select - Url - Regex - Address - Fullname label: type: string maxLength: 128 description: type: string maxLength: 256 nullable: true required: type: boolean config: type: object properties: placeholder: type: string maxLength: 256 minLength: type: number maxLength: type: number minValue: type: number maxValue: type: number format: type: string maxLength: 128 customFormat: type: string maxLength: 128 options: type: array items: type: object required: - value properties: label: type: string value: type: string defaultValue: type: string parts: type: array items: type: object required: - enabled - name - type - required properties: enabled: type: boolean name: type: string type: type: string enum: - Text - Number - Date - Checkbox - Select - Url - Regex - Address - Fullname label: type: string minLength: 1 description: type: string required: type: boolean config: type: object properties: placeholder: type: string maxLength: 256 minLength: type: number maxLength: type: number minValue: type: number maxValue: type: number format: type: string maxLength: 128 customFormat: type: string maxLength: 128 options: type: array items: type: object required: - value properties: label: type: string value: type: string defaultValue: type: string createdAt: type: number sieOrder: type: number '400': description: Bad Request security: [] summary: Get full sign-in experience description: Get the full sign-in experience configuration. /api/.well-known/account-center: get: operationId: GetWellKnownAccountCenter tags: - Well-known parameters: [] responses: '200': description: The default account center configuration. content: application/json: schema: type: object required: - tenantId - id - enabled - fields - webauthnRelatedOrigins - deleteAccountUrl - customCss properties: tenantId: type: string maxLength: 21 id: type: string minLength: 1 maxLength: 21 enabled: type: boolean fields: type: object properties: name: type: string enum: - 'Off' - ReadOnly - Edit avatar: type: string enum: - 'Off' - ReadOnly - Edit profile: type: string enum: - 'Off' - ReadOnly - Edit email: type: string enum: - 'Off' - ReadOnly - Edit phone: type: string enum: - 'Off' - ReadOnly - Edit password: type: string enum: - 'Off' - ReadOnly - Edit username: type: string enum: - 'Off' - ReadOnly - Edit social: type: string enum: - 'Off' - ReadOnly - Edit customData: type: string enum: - 'Off' - ReadOnly - Edit mfa: type: string enum: - 'Off' - ReadOnly - Edit session: type: string enum: - 'Off' - ReadOnly - Edit webauthnRelatedOrigins: type: array items: type: string deleteAccountUrl: type: string maxLength: 2048 nullable: true customCss: type: string nullable: true security: [] summary: Get default account center description: Get the default account center configuration. /api/.well-known/management.openapi.json: get: operationId: GetWellKnownManagementOpenapiJson tags: - Well-known parameters: [] responses: '200': description: The JSON document. content: application/json: {} security: [] summary: Get Management API swagger JSON description: The endpoint for the Management API JSON document. The JSON conforms to the [OpenAPI v3.0.1](https://spec.openapis.org/oas/v3.0.1) (a.k.a. Swagger) specification. /api/.well-known/experience.openapi.json: get: operationId: GetWellKnownExperienceOpenapiJson tags: - Well-known parameters: [] responses: '200': description: The JSON document. content: application/json: {} security: [] summary: Get Experience API swagger JSON description: The endpoint for the Experience API JSON document. The JSON conforms to the [OpenAPI v3.0.1](https://spec.openapis.org/oas/v3.0.1) (a.k.a. Swagger) specification. /api/.well-known/user.openapi.json: get: operationId: GetWellKnownUserOpenapiJson tags: - Well-known parameters: [] responses: '200': description: The JSON document. content: application/json: {} security: [] summary: Get User API swagger JSON description: The endpoint for the User API JSON document. The JSON conforms to the [OpenAPI v3.0.1](https://spec.openapis.org/oas/v3.0.1) (a.k.a. Swagger) specification. components: 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