Short answer: you validate OTP (one-time code) by submitting the relevant self-service flow update, not via a separate “validate code” endpoint. - For MFA via SMS/email: start a login flow with aal=aal2, then submit the login flow with method code and the code value. [[SMS 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms)] - For registration or login with one-time code (passwordless): submit the registration/login flow with method set to code and include the code field. The API schema shows the update payload containing method: "code" and code: "<OTP>". [[Update registration](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json)] - For email/phone verification: submit the verification flow with the code using the verification UI form action returned by getVerificationFlow. [[Verification flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#verification-flow); [getVerificationFlow](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json)] There isn’t a standalone “validate OTP” API; you always POST the code to the flow’s ui.action with the appropriate method field. If you need exact request bodies, use the flow’s UI nodes/attributes returned by the respective get flow endpoints. [[getVerificationFlow](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json)]

It’s triggered when you submit the corresponding self‑service flow with method=code (first step of the flow). There’s no separate “send code” API. - Verification (email/phone): POST /self-service/verification with method set to code and the user’s email/phone; this sends the verification code. [[Submit verification flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#submit-verification-flow); [updateVerificationFlow](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json)] - Passwordless login or registration via one-time code: submitting the login/registration flow with method=code and the identifier (email/phone) triggers sending the OTP for the next step. [[Passwordless one-time code](https://www.ory.sh/docs/kratos/passwordless/one-time-code); [Enable SMS OTP](https://www.ory.sh/docs/kratos/passwordless/one-time-code#enable-sms-one-time-code-otp)] - MFA via code (AAL2): start a login flow with aal=aal2, then posting the flow with method=code to the flow’s ui.action sends the code to the configured channel. [[SMS and Email 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms)] In all cases, you POST to the flow’s ui.action URL with method=code (and identifier if required); Kratos then dispatches the OTP via the configured email/SMS courier. [[Send SMS](https://www.ory.sh/docs/kratos/emails-sms/sending-sms)]

A message from kapa.ai

Here’s an end-to-end outline for “OTP code” authentication (email/SMS one-time code) using Ory Hydra (OAuth2/OIDC) with Ory Kratos and a custom UI. Prereqs: - In Kratos, enable passwordless one-time code (code.passwordless_enabled=true) and configure email/SMS delivery. [[Email/SMS OTP](https://www.ory.sh/docs/kratos/passwordless/one-time-code); [Enable SMS OTP](https://www.ory.sh/docs/kratos/passwordless/one-time-code#enable-sms-one-time-code-otp)] - If you also want MFA via code (AAL2), enable code.mfa_enabled separately; note passwordless and MFA via code can’t be used together in the same flow. [[SMS and Email 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms)] Flow: OAuth2 login with passwordless OTP (custom UI) 1) Client starts OAuth2 flow at Hydra: - Browser → GET /oauth2/auth?... on Hydra. If no user session, Hydra redirects to your Login UI with login_challenge. [[Login/consent flow](https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow)] 2) Your Login UI begins a Kratos login flow: - Create a browser login flow via Kratos and render fields from flow.ui (custom UI). Only show method=code for passwordless. [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration); [Passwordless login UI mapping](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-advanced-integration#passwordless-authentication)] 3) Step 1 (send code): - User enters identifier (email or phone). - Submit the login flow to flow.ui.action with method=code and the identifier. - Kratos dispatches the OTP to the configured email/SMS channel. [[Email/SMS OTP](https://www.ory.sh/docs/kratos/passwordless/one-time-code); [SMS and Email 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms)] 4) Step 2 (verify code): - Show input for the code. - Submit the same login flow (or the next step returned by Kratos) to flow.ui.action with method=code and the received code. - On success, Kratos creates a user session. [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)] 5) Hand session back to Hydra: - After successful Kratos login, your Login UI app accepts the Hydra login request using the login_challenge (server-side against Hydra Admin API in your app), then redirects the browser back to Hydra’s redirect for consent. [[Login/consent flow](https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow)] 6) Consent UI: - Your app fetches the consent request, renders scopes, and on user approval accepts the consent request, then Hydra redirects back to the client with the authorization code. [[Login/consent flow](https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow)] Optional: account verification via code - If you also need email/phone verification, run a Kratos verification flow (method=code) which sends a code and marks the address verified after successful submission. [[Verification flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#verification-flow)] Notes and tips: - There is no standalone “send code” or “validate code” API; you always POST to the flow’s ui.action with method=code and the appropriate fields. [[Email/SMS OTP](https://www.ory.sh/docs/kratos/passwordless/one-time-code)] - Ensure your identity schema marks the identifier (email/phone) for the code method and configure the courier (SMTP/SMS webhook). [[SMS and Email 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms); [Enable SMS OTP](https://www.ory.sh/docs/kratos/passwordless/one-time-code#enable-sms-one-time-code-otp)] - For the custom UI, render only the nodes relevant to code and follow the flow’s ui nodes and action URL. [[Advanced passwordless UI](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-advanced-integration#passwordless-authentication)]

A message from kapa.ai

Here’s an end-to-end outline for implementing one-time-code (OTP) authentication with a custom UI when using Ory Kratos (identities) together with Ory Hydra (OAuth2). The key is: OTP is always executed inside Kratos self-service flows; Hydra delegates authentication to Kratos and consumes the resulting session. Prerequisites - In Kratos, enable the code method for passwordless, or for MFA, depending on your use case: - Passwordless login/registration via email/SMS: enable selfservice.methods.code.passwordless_enabled=true. [[One-time code](https://www.ory.sh/docs/kratos/passwordless/one-time-code)] - MFA via email/SMS: enable selfservice.methods.code.mfa_enabled=true and configure the identifier in the identity schema. [[SMS and Email 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms)] - Configure email/SMS delivery (SMTP and/or SMS webhook). [[Email templates](https://www.ory.sh/docs/kratos/emails-sms/custom-email-templates); [Send emails](https://www.ory.sh/docs/kratos/emails-sms/sending-emails-smtp); [Send SMS](https://www.ory.sh/docs/kratos/emails-sms/sending-sms)] - For OAuth2 with Hydra: set up your OAuth2 client to use your custom UI for login and consent, with login handled by Kratos. (The knowledge sources don’t include detailed Hydra ↔️ Kratos wiring steps; proceed if you already have login/consent handlers.) Flow A: Passwordless login (single-page custom UI) 1) App starts OAuth2 authorization with Hydra - Your frontend hits your backend’s /oauth2/authorize (Hydra). Hydra redirects the user to your login UI because they’re not authenticated. (Detailed Hydra steps aren’t in the sources.) 2) Create a Kratos login flow (browser) - Your login UI calls Kratos: GET /self-service/login/browser to create the flow and receive ui nodes and the ui.action URL. [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)] 3) Step 1: Send OTP - Render only the email/phone field from the login flow’s ui nodes for method=code. - Submit to flow’s ui.action with: - method=code - identifier (email or phone matching your identity schema) - Kratos sends the OTP via email/SMS. [[One-time code](https://www.ory.sh/docs/kratos/passwordless/one-time-code)] 4) Step 2: Verify OTP - After submission, Kratos returns a next-step login flow state containing a code input node. - Your UI renders the code input and posts back to ui.action with: - method=code - code=<6-digit> - On success, Kratos establishes a session. [[Self-service flows](https://www.ory.sh/docs/kratos/self-service)] 5) Return control to Hydra - With a valid Kratos session cookie, redirect back to your backend’s login handler so Hydra can accept the login and proceed to consent and token issuance. (Hydra specifics not in sources.) Flow B: Passwordless registration via OTP (same single input UX) - If you want a unified “enter email, receive OTP” that registers users who don’t yet exist: - On the first submission, your backend determines whether the identifier exists and triggers either a registration or login flow accordingly. This requires custom UI logic. [[Custom UI advice](https://github.com/ory/kratos/discussions/4294)] - Registration via OTP: 1) Create registration flow: GET /self-service/registration/browser. 2) Submit with method=code and identifier to send the OTP. [[One-time code](https://www.ory.sh/docs/kratos/passwordless/one-time-code)] 3) Submit code to ui.action to complete registration. You can add a post-registration session hook to sign the user in directly. [[Self-service flows](https://www.ory.sh/docs/kratos/self-service)] Flow C: MFA via OTP (AAL2) - For users already logged in at AAL1, to step-up: 1) Start a login flow with aal=aal2: GET /self-service/login/browser?aal=aal2. [[SMS and Email 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms)] 2) Submit method=code to send OTP to the configured channel (email or SMS). 3) Submit method=code with the received code to upgrade the session to AAL2. Key implementation notes - Always use the flow’s returned ui.action URL and ui nodes to know which fields to render and submit; there’s no separate “send code” or “validate code” endpoint. You always POST to the flow with method=code and the required fields. [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)] - For SMS, configure an SMS channel webhook; Kratos posts code + metadata to your webhook. [[SMS and Email 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms)] - For email, configure SMTP and optionally customize templates like login_code.valid or registration_code.valid. [[Email templates](https://www.ory.sh/docs/kratos/emails-sms/custom-email-templates)] - One-time code passwordless and MFA via code cannot be used simultaneously for the same project; enabling MFA via code disables using code for passwordless login. Plan your strategy accordingly. [[SMS and Email 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms)] If you need exact request bodies, fetch the flow (getLoginFlow/getRegistrationFlow) and inspect the ui.nodes; submit exactly those fields back to ui.action with method=code. [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)]

Here’s an end-to-end flow for OTP (one-time code via email/SMS) authentication using Ory Hydra (OAuth2/OIDC) with Ory Kratos and a custom UI. Prerequisites - In Kratos, enable passwordless one-time code: selfservice.methods.code.passwordless_enabled=true, and configure email/SMS delivery and identity schema (email or phone marked as code identifier). [[Email/SMS OTP](https://www.ory.sh/docs/kratos/passwordless/one-time-code); [Custom schema](https://www.ory.sh/docs/kratos/passwordless/one-time-code#custom-identity-schema)] - Use Kratos self-service flows with your own UI (browser endpoints). [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)] - Hydra configured with your custom login and consent URLs. [[Hydra login/consent flow](https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow)] Flow 1) Client starts OAuth2/OIDC at Hydra - Browser hits Hydra /oauth2/auth?...; Hydra checks for end-user session and then redirects to your login endpoint with login_challenge. [[Hydra login/consent flow](https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow)] 2) Your Login UI initializes a Kratos browser login flow - Create browser login flow and render only the “code” method fields (custom UI). [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration); [Passwordless UI mapping](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-advanced-integration#passwordless-authentication)] 3) Step 1: Send OTP - User enters identifier (email/phone). - POST to the flow’s ui.action with method=code and the identifier. Kratos sends the one-time code via the configured courier (email/SMS). [[Email/SMS OTP](https://www.ory.sh/docs/kratos/passwordless/one-time-code)] 4) Step 2: Verify OTP and create session - Show code input. - POST to the flow’s ui.action with method=code and the received code. On success, Kratos issues a session. [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)] 5) Hand the session back to Hydra (login accept) - Using login_challenge, your app accepts the Hydra login request and redirects back to Hydra to continue with consent. [[Hydra login/consent flow](https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow)] 6) Consent UI - Fetch consent request, display scopes, accept or reject, then Hydra redirects back to the OAuth2 client with the authorization code. [[Hydra login/consent flow](https://www.ory.sh/docs/oauth2-oidc/custom-login-consent/flow)] Important notes - There is no standalone “send” or “validate” OTP API—both steps are done by submitting the self-service login flow to ui.action with method=code (first submit sends, second verifies). [[Email/SMS OTP](https://www.ory.sh/docs/kratos/passwordless/one-time-code)] - Ensure the identity schema marks the identifier for code (via email or sms). [[Custom schema](https://www.ory.sh/docs/kratos/passwordless/one-time-code#custom-identity-schema)] - For custom UI, always render and submit the fields provided by the flow (nodes/action/method). [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)] Optional - If you need OTP as MFA (AAL2) instead of passwordless, start a login flow with aal=aal2 and use method=code; note that MFA via code cannot be used for passwordless at the same time. [[SMS and Email 2FA](https://www.ory.sh/docs/kratos/mfa/mfa-via-sms)]

Short answer: both are POSTs to the same flow’s ui.action with method=code, but the payload fields differ. - Step 3 (send OTP): include the identifier (email/phone) and method=code (plus CSRF token for browser flows). This triggers sending the code. [[Submit verification flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#submit-verification-flow); [updateLoginFlow schema](https://raw.githubusercontent.com/ory/docs/master/docs/reference/api.json)] - Step 4 (verify OTP): include the received code and method=code (plus CSRF token for browser flows). Do not include the identifier unless you intend to resend. [[Submit verification flow](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration#submit-verification-flow); [updateVerificationFlow schema](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json)] Notes: - For login: method=code with identifier to send; method=code with code to verify. [[updateLoginFlow](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json); [Ory API updateLoginFlow](https://raw.githubusercontent.com/ory/docs/master/docs/reference/api.json)] - For verification: method=code with email to send; method=code with code to verify. Including email after a code was sent will invalidate and resend. [[updateVerificationFlow](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json); [Ory API updateVerificationFlow](https://raw.githubusercontent.com/ory/docs/master/docs/reference/api.json)]

Short answer: there’s no explicit “this was registration vs login” flag returned by Kratos. You need to infer it from the flow you completed or from your own app logic. Practical ways: - Track which flow you started: if you created and completed a registration flow (self-service registration) with method=code, it was a new signup; if you completed a login flow, it was an existing-user sign-in. [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)] - If you auto-login after registration, that session is created via the registration flow’s “session” after-hook or the “Sign In After Registration” toggle in Ory Network. If the session was created right after a registration flow, you can treat it as a signup. [[Successful registration](https://www.ory.sh/docs/kratos/self-service/flows/user-registration#successful-registration); [Log in users after registration](https://www.ory.sh/docs/identities/sign-in/actions#log-in-users-after-registration)] If your UI unifies signup and login into one screen, keep a flag in your app indicating whether you initialized a registration or a login flow before submitting method=code, and decide based on that. The docs do not mention a built-in response field distinguishing the two. [[Integration basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)]

Kratos does not auto-create identities during the login flow. If you want “login with phone (code) and create the user if they don’t exist,” you must run the registration flow (method=code) for first-time users, and the login flow (method=code) for existing users. A single-page UX is possible, but your app needs to decide which flow to start based on whether the identifier exists. [[Self-service flows](https://www.ory.sh/docs/kratos/self-service); [One-time code](https://www.ory.sh/docs/kratos/passwordless/one-time-code); [Custom UI discussion](https://github.com/ory/kratos/discussions/4294)]

I’m sorry, but the knowledge sources don’t list an API to look up an identity by phone number (or email) directly. The documented admin APIs fetch by internal ID or by externalID, and can include credentials, but not search by trait/identifier. [[getIdentity](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json); [getIdentity by externalID](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json)] Typical approaches: - Your app keeps a directory/index to map phone → identity ID, then uses GET /admin/identities/{id}. [[getIdentity](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json)] - Try the flow: if you start a registration with that phone and Kratos returns “identifier exists already” (error 4000007), you know the user already exists. [[4000007 message](https://www.ory.sh/docs/kratos/concepts/ui-messages#an-account-with-the-same-identifier-email-phone-username--exists-already-4000007)]

There’s no API to “lookup by phone” in Kratos, so your app must decide which flow to start. You have two practical, documented options: - Optimistic registration, fallback to login: 1) Start a registration flow (method=code) with the phone number. 2) If Kratos responds with “An account with the same identifier … exists already” (4000007), switch to a login flow (method=code) with the same phone. [[4000007](https://www.ory.sh/docs/kratos/concepts/ui-messages#an-account-with-the-same-identifier-email-phone-username--exists-already-4000007); [Flows basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)] - Pre-check in your backend (custom directory/index): - Maintain your own index mapping phone → identity ID, then choose registration vs login accordingly. The docs don’t provide a Kratos API to query by phone. [[Flows basics](https://www.ory.sh/docs/kratos/bring-your-own-ui/custom-ui-basic-integration)] If you want a single “enter phone, then OTP” UX, build a custom UI: after the user submits the phone number, either attempt registration first and catch 4000007 to switch to login, or consult your own index to choose the appropriate flow. [[Custom UI advice](https://github.com/ory/kratos/discussions/4294)]

Short answer: because that endpoint isn’t available. The documented Admin Identity APIs don’t include a “search by credentials identifier” (phone/email) route. You can get an identity by its ID (or external_id) and list identities with limited filters, but not query by a phone/email identifier directly. [[REST API guidelines](https://www.ory.sh/docs/open-source/guidelines/rest-api-guidelines#the-design-for-openapi); [Retrieve subset issue](https://github.com/ory/network/issues/305)] Implications: - There’s no official API to look up an identity by phone number; you must either: - Try registration first and switch to login on conflict 4000007, or - Maintain your own index to map phone → identity ID. [[4000007](https://www.ory.sh/docs/kratos/concepts/ui-messages#an-account-with-the-same-identifier-email-phone-username--exists-already-4000007); [Custom UI discussion](https://github.com/ory/kratos/discussions/4294)] Note: Related requests to support filtering/batching on admin identity listing have been discussed; current guidance suggests workarounds like caching or parallel gets, not identifier search. [[Retrieve subset issue](https://github.com/ory/network/issues/305); [Rate limits issue](https://github.com/ory/network/issues/396)]

Kratos checks identifier uniqueness during the registration flow. When you submit the registration flow (method=code) with a phone number that’s already used as an identifier, Kratos validates the payload against its credentials/index and returns a UI error: - “An account with the same identifier (email, phone, username, …) exists already.” (id 4000007) This is how you detect “identity already exists” without a lookup API. On receiving 4000007 from the registration submission, switch your UI to the login flow for the same phone number. [[4000007](https://www.ory.sh/docs/kratos/concepts/ui-messages#an-account-with-the-same-identifier-email-phone-username--exists-already-4000007); [Custom UI advice](https://github.com/ory/kratos/discussions/4294)] There’s no documented admin endpoint to pre-check by phone (e.g., /admin/identities?credentials_identifier). You either: - Attempt registration and handle 4000007, or - Maintain your own index to decide before starting a flow. [[4000007](https://www.ory.sh/docs/kratos/concepts/ui-messages#an-account-with-the-same-identifier-email-phone-username--exists-already-4000007); [Custom UI advice](https://github.com/ory/kratos/discussions/4294)]

I’m sorry, but the knowledge sources don’t describe Kratos’s internal algorithm for checking identifier uniqueness. They only state the observable behavior: during registration, if the submitted identifier (email/phone/username marked as an identifier in the identity schema) is already in use, Kratos returns the 4000007 UI error “An account with the same identifier … exists already.” [[4000007](https://www.ory.sh/docs/kratos/concepts/ui-messages#an-account-with-the-same-identifier-email-phone-username--exists-already-4000007); [Registration validation](https://www.ory.sh/docs/kratos/self-service/flows/user-registration#registration-form-validation); [Choosing identifier](https://www.ory.sh/docs/kratos/manage-identities/customize-identity-schema#choosing-between-username-email-and-phone-number)] If you need exact implementation details, they aren’t covered in the provided docs. The documented guidance focuses on configuring which traits are identifiers and handling the resulting errors/flows. [[Password login identifier](https://www.ory.sh/docs/kratos/manage-identities/customize-identity-schema#password-login-identifier)]

Short answer: there is no documented API to search identities by an arbitrary trait key (e.g., phone/email) directly. What you can do today: - List identities, but filtering is limited and not by arbitrary traits; batch filtering by IDs isn’t supported either. [[listIdentities](https://raw.githubusercontent.com/ory/docs/master/docs/reference/api.json)] - Get by identity ID, or by external_id using the dedicated “by external” route. [[getIdentity](https://raw.githubusercontent.com/ory/kratos/master/spec/api.json); [external_id guide](https://www.ory.sh/docs/kratos/manage-identities/external-id)] - Common workaround: try registration first and, if you receive the “identifier exists already” (4000007) message, switch to login; or maintain your own index mapping trait→identity. [[4000007 message](https://www.ory.sh/docs/kratos/concepts/ui-messages#an-account-with-the-same-identifier-email-phone-username--exists-already-4000007); [Retrieve subset issue](https://github.com/ory/network/issues/305)] If searching by a custom key is critical, consider using external_id for that key (ensures uniqueness and supports lookup by dedicated API). [[external_id guide](https://www.ory.sh/docs/kratos/manage-identities/external-id)]

Yes. When you submit a registration flow with a phone number that’s already used as an identifier, Kratos rejects the registration and returns the UI error “An account with the same identifier (email, phone, username, …) exists already.” (message id 4000007). You should handle this error and switch to a login flow. [[4000007](https://www.ory.sh/docs/kratos/concepts/ui-messages#an-account-with-the-same-identifier-email-phone-username--exists-already-4000007); [Registration validation](https://www.ory.sh/docs/kratos/self-service/flows/user-registration#registration-form-validation); [Phone identifier](https://www.ory.sh/docs/kratos/manage-identities/customize-identity-schema#phone-number)]