How do I request for OTP using API?

[jjkoh95]

Is there any API to request OTP?
Currently I'm using self-service/registration with payload below, which returns me 400 status code.
Is this expected?
The 400 status seems to be signalling something wrong despite they actually send OTP underneath.

{
    "method": "code",
    "traits": {
        "phone_number": "+60123456789"
    }
}

[MarkusThielker]

Could you please clarify what you are trying to accomplish?

[vinckr]

Thanks Markus,
the use case would have been my first question as well 😁

There might be confusion why an OTP is still sent even though they get back a 400 error? At least that is how I understood it in first pass. The error-handling docs say that a 400 often still contains a valid flow object, so that might be the source of the confusion, but I will let @jjkoh95 elaborate. [Error handling]

[jjkoh95]

Thanks @MarkusThielker @vinckr

Yes, that's exactly my confusion.
I'm wondering if it's the right way to request for OTP to complete login/registration flow or if there is a more elegant way to achieve this specifically via API.

So for more context, I have flow below:

1. initialize registration flow
2. request for OTP (this is where I receive 400 and wondering if there's a separate API to handle this or if this is the recommended way to request for OTP)
3. submit OTP (this is the same payload from 2, with OTP in the body)

[vinckr]

Hello @jjkoh95

You’re not missing a separate “request OTP” endpoint – requesting the OTP and completing the flow are both done via the same self‑service flow endpoints. There is no dedicated “send code” API.

For registration with one‑time code, the intended pattern is:

1. Create the registration flow

GET /self-service/registration/api
or /browser for browser flows. createNativeRegistrationFlow

2. First submit – request the code
   Call POST /self-service/registration?flow= (updateRegistrationFlow) with:

{
  "method": "code",
  "traits": {
    "phone_number": "+60123456789"
  },
  "csrf_token": "..."   // browser only
}

This uses the updateRegistrationFlowWithCodeMethod body. method and traits are required; code is not required in the first step and is only present when the user submits the OTP. updateRegistrationFlow body

When the payload is valid, this first call both:

sends the OTP (using the courier/email/SMS config), and
returns an updated registration flow (200 for API, or a 303 redirect for browser flows). Registration form validation

3. Second submit – verify the code

Call the same endpoint again with:

{
  "method": "code",
  "traits": {
    "phone_number": "+60123456789"
  },
  "code": "123456",
  "csrf_token": "..."
}

Here code is set and Kratos will complete the flow if the OTP is valid. updateRegistrationFlow body

As for the question around 400 error

If you get 400 and the OTP is sent, that typically means:

• Kratos accepted enough data to send a code
• but something in the payload is invalid from Kratos’ point of view (e.g. trait not matching the identity schema, missing CSRF token in browser flows, code method not configured as passwordless / identifier not marked, etc.), so it responds with 400 and error messages.

[jjkoh95]

Hi @vinckr thanks for your detailed explanation

I have followed exactly as you mentioned above.
I couldn't figure out why I'm getting 400 on step (2), requesting for code.
If you have some time, please help me understand what potentially leads to 400 for my step (2).
Here I attach my config, request and response body for reference.

Thanks a lot. Please let me know if you need more information from my side.

kratos.yaml

version: v1.3.0

dsn: postgres://kratos:secret@postgres:5432/kratos?sslmode=disable

serve:
  public:
    base_url: http://127.0.0.1:4433/
    cors:
      enabled: true
  admin:
    base_url: http://kratos:4434/

selfservice:
  default_browser_return_url: http://127.0.0.1:4455/welcome
  allowed_return_urls:
    - http://127.0.0.1:4455
    - http://localhost:19006/Callback
    - exp://localhost:8081/--/Callback

  methods:
    password:
      enabled: false
    totp:
      config:
        issuer: Kratos
      enabled: true
    lookup_secret:
      enabled: true
    link:
      enabled: false
    code:
      enabled: true
      passwordless_enabled: true

  flows:
    error:
      ui_url: http://127.0.0.1:4455/error

    settings:
      ui_url: http://127.0.0.1:4455/settings
      privileged_session_max_age: 15m
      required_aal: highest_available

    recovery:
      enabled: true
      ui_url: http://127.0.0.1:4455/recovery
      use: code

    verification:
      enabled: true
      ui_url: http://127.0.0.1:4455/verification
      use: code
      after:
        default_browser_return_url: http://127.0.0.1:4455/welcome

    logout:
      after:
        default_browser_return_url: http://127.0.0.1:4455/login

    login:
      ui_url: http://127.0.0.1:4455/login
      lifespan: 10m

    registration:
      lifespan: 10m
      ui_url: http://127.0.0.1:4455/registration

log:
  level: debug
  format: text
  leak_sensitive_values: true

secrets:
  cookie:
    - PLEASE-CHANGE-ME-I-AM-VERY-INSECURE
  cipher:
    - 32-LONG-SECRET-NOT-SECURE-AT-ALL

ciphers:
  algorithm: xchacha20-poly1305

hashers:
  algorithm: bcrypt
  bcrypt:
    cost: 8

identity:
  default_schema_id: default
  schemas:
    - id: default
      url: file:///etc/config/kratos/identity.schema.json

courier:
  smtp:
    connection_uri: smtps://test:test@mailslurper:1025/?skip_ssl_verify=true
  channels:
    - id: sms
      type: http
      request_config:
        url: http://mock-sms:8765/sms
        method: POST
        body: base64://ZnVuY3Rpb24oY3R4KSB7CiAgVG86IGN0eC5yZWNpcGllbnQsCiAgQm9keTogY3R4LmJvZHksCn0=
        headers:
          Content-Type: application/json

feature_flags:
  use_continue_with_transitions: true

APIs

1. GET {{KRATOS_PUBLIC_URL}}/self-service/registration/api
2. POST {{KRATOS_PUBLIC_URL}}/self-service/registration?flow={{FLOW}}

Request:

{
    "method": "code",
    "traits": {
        "phone_number": "+60123456789"
    }
}

Response:

• status: 400 Bad Request
• body:

{
    "id": "e1ccdaa2-d55e-4833-bd65-148d6466e4fd",
    "type": "api",
    "expires_at": "2025-12-04T01:23:19.687114Z",
    "issued_at": "2025-12-04T01:13:19.687114Z",
    "request_url": "http://localhost:4433/self-service/registration/api",
    "active": "code",
    "ui": {
        "action": "http://127.0.0.1:4433/self-service/registration?flow=e1ccdaa2-d55e-4833-bd65-148d6466e4fd",
        "method": "POST",
        "nodes": [
            {
                "type": "input",
                "group": "default",
                "attributes": {
                    "name": "csrf_token",
                    "type": "hidden",
                    "value": "",
                    "required": true,
                    "disabled": false,
                    "node_type": "input"
                },
                "messages": [],
                "meta": {}
            },
            {
                "type": "input",
                "group": "default",
                "attributes": {
                    "name": "traits.phone_number",
                    "type": "hidden",
                    "value": "+60123456789",
                    "required": true,
                    "autocomplete": "tel",
                    "disabled": false,
                    "node_type": "input"
                },
                "messages": [],
                "meta": {
                    "label": {
                        "id": 1070002,
                        "text": "Phone Number",
                        "type": "info",
                        "context": {
                            "name": "traits.phone_number",
                            "title": "Phone Number"
                        }
                    }
                }
            },
            {
                "type": "input",
                "group": "code",
                "attributes": {
                    "name": "method",
                    "type": "hidden",
                    "value": "code",
                    "disabled": false,
                    "node_type": "input"
                },
                "messages": [],
                "meta": {}
            },
            {
                "type": "input",
                "group": "code",
                "attributes": {
                    "name": "code",
                    "type": "text",
                    "required": true,
                    "disabled": false,
                    "node_type": "input"
                },
                "messages": [],
                "meta": {
                    "label": {
                        "id": 1070012,
                        "text": "Registration code",
                        "type": "info"
                    }
                }
            },
            {
                "type": "input",
                "group": "code",
                "attributes": {
                    "name": "method",
                    "type": "submit",
                    "value": "code",
                    "disabled": false,
                    "node_type": "input"
                },
                "messages": [],
                "meta": {
                    "label": {
                        "id": 1070009,
                        "text": "Continue",
                        "type": "info"
                    }
                }
            },
            {
                "type": "input",
                "group": "code",
                "attributes": {
                    "name": "resend",
                    "type": "submit",
                    "value": "code",
                    "disabled": false,
                    "node_type": "input"
                },
                "messages": [],
                "meta": {
                    "label": {
                        "id": 1070008,
                        "text": "Resend code",
                        "type": "info"
                    }
                }
            },
            {
                "type": "input",
                "group": "profile",
                "attributes": {
                    "name": "screen",
                    "type": "submit",
                    "value": "credential-selection",
                    "disabled": false,
                    "node_type": "input"
                },
                "messages": [],
                "meta": {
                    "label": {
                        "id": 1040008,
                        "text": "Back",
                        "type": "info"
                    }
                }
            }
        ],
        "messages": [
            {
                "id": 1040005,
                "text": "A code has been sent to the address(es) you provided. If you have not received a message, check the spelling of the address and retry the registration.",
                "type": "info"
            }
        ]
    },
    "organization_id": null,
    "transient_payload": {},
    "state": "sent_email"
}