Endpoints for customizing Logto sign-in experience. See [🎨 Customize sign-in experience](https://docs.logto.io/docs/recipes/customize-sie/) to learn more about how the configuration works and reflects on the user interface.
openapi: 3.0.1
info:
title: Logto API references Account center Sign-in experience 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: Sign-in experience
description: Endpoints for customizing Logto sign-in experience. See [🎨 Customize sign-in experience](https://docs.logto.io/docs/recipes/customize-sie/) to learn more about how the configuration works and reflects on the user interface.
paths:
/api/sign-in-exp:
get:
operationId: GetSignInExp
tags:
- Sign-in experience
parameters: []
responses:
'200':
description: Default sign-in experience settings.
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
- forgotPasswordMethods
- passkeySignIn
- signUpProfileFields
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
description: The primary branding color for the sign-in page (both light/dark mode).
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
description: Cloud only. Whether to hide the Logto branding on hosted sign-in pages.
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
description: The language detection policy for the sign-in page.
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
description: Sign-in method settings.
signUp:
type: object
required:
- identifiers
- password
- verify
properties:
identifiers:
type: array
items:
type: string
enum:
- username
- email
- phone
description: Allowed identifiers when signing-up.
password:
type: boolean
description: Whether the user is required to set a password when signing-up.
verify:
type: boolean
description: Whether the user is required to verify their email/phone when signing-up.
secondaryIdentifiers:
type: array
items:
type: object
required:
- identifier
properties:
identifier:
oneOf:
- type: string
enum:
- username
- email
- phone
- type: string
enum:
- emailOrPhone
verify:
type: boolean
description: Additional identifiers required during sign-up. Once specified, users will be prompted to provide these identifiers when creating an account.
description: Sign-up method settings.
socialSignIn:
type: object
properties:
automaticAccountLinking:
type: boolean
skipRequiredIdentifiers:
type: boolean
socialSignInConnectorTargets:
type: array
items:
type: string
description: Enabled social sign-in connectors, will displayed on the sign-in page.
signInMode:
type: string
enum:
- SignIn
- Register
- SignInAndRegister
customCss:
type: string
nullable: true
customContent:
type: object
additionalProperties:
type: string
description: Custom content to display on experience flow pages. the page pathname will be the config key, the content will be the config value.
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
description: Password policies to adjust the password strength requirements.
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
description: MFA settings
adaptiveMfa:
type: object
properties:
enabled:
type: boolean
description: Adaptive MFA settings.
singleSignOnEnabled:
type: boolean
supportEmail:
type: string
nullable: true
description: The support email address to display on the error pages.
supportWebsiteUrl:
type: string
nullable: true
description: The support website URL to display on the error pages.
unknownSessionRedirectUrl:
type: string
nullable: true
description: The fallback URL to redirect users when the sign-in session does not exist or unknown. Client should initiates a new authentication flow after the redirection.
captchaPolicy:
type: object
properties:
enabled:
type: boolean
sentinelPolicy:
type: object
properties:
maxAttempts:
type: number
lockoutDuration:
type: number
description: Custom sentinel policy settings. Use this field to customize the user lockout policy. The default value is 100 failed attempts within one hour. The user will be locked out for 60 minutes after exceeding the limit.
emailBlocklistPolicy:
type: object
properties:
blockDisposableAddresses:
type: boolean
blockSubaddressing:
type: boolean
description: Whether to block sub-addresses. (E.g., example+shopping@test.com)
customBlocklist:
type: array
items:
type: string
description: Custom blocklist of email addresses or domains.
blockDisposableAddress:
description: Cloud only. Whether to block disposable email addresses. Once enabled, Logto will check the email domain against a list of known disposable email domains. If the domain is found in the list, the email address will be blocked.
description: Define email restriction policies. Users will be prohibited from registering or linking any email addresses that are included in the blocklist.
forgotPasswordMethods:
type: array
items:
type: string
enum:
- EmailVerificationCode
- PhoneVerificationCode
nullable: true
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
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Default sign-in experience settings not found.
summary: Get default sign-in experience settings
description: Get the default sign-in experience settings.
patch:
operationId: UpdateSignInExp
tags:
- Sign-in experience
parameters:
- name: removeUnusedDemoSocialConnector
in: query
required: false
schema:
type: string
description: Whether to remove unused demo social connectors. (These demo social connectors are only used during cloud user onboarding)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
tenantId:
type: string
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
description: Specify the primary branding color for the sign-in page (both light/dark mode).
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
description: Cloud only. Whether to hide the Logto branding on hosted sign-in pages.
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
description: Control the language detection policy for the sign-in page.
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
description: Sign-in method settings
signUp:
type: object
required:
- identifiers
- password
- verify
properties:
identifiers:
type: array
items:
type: string
enum:
- username
- email
- phone
description: Specify allowed identifiers when signing-up.
password:
type: boolean
description: Whether the user is required to set a password when signing-up.
verify:
type: boolean
description: Whether the user is required to verify their email/phone when signing-up.
secondaryIdentifiers:
type: array
items:
type: object
required:
- identifier
properties:
identifier:
oneOf:
- type: string
enum:
- username
- email
- phone
- type: string
enum:
- emailOrPhone
verify:
type: boolean
description: Sign-up method settings
socialSignIn:
type: object
properties:
automaticAccountLinking:
type: boolean
skipRequiredIdentifiers:
type: boolean
socialSignInConnectorTargets:
type: array
items:
type: string
description: Specify the social sign-in connectors to display on the sign-in page.
signInMode:
type: string
enum:
- SignIn
- Register
- SignInAndRegister
customCss:
type: string
nullable: true
customContent:
type: object
additionalProperties:
type: string
description: Custom content to display on experience flow pages. the page pathname will be the config key, the content will be the config value.
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
description: Password policies to adjust the password strength requirements.
mfa:
type: object
required:
- factors
- policy
properties:
factors:
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/logto/refs/heads/main/openapi/logto-sign-in-experience-api-openapi.yml