---
title: "Submit a Login Flow"
method: POST
path: "/self-service/login"
tags: ["v0alpha2"]
---

# Submit a Login Flow

`POST /self-service/login`

:::info

This endpoint is EXPERIMENTAL and subject to potential breaking changes in the future.

:::

Use this endpoint to complete a login flow. This endpoint
behaves differently for API and browser flows.

API flows expect `application/json` to be sent in the body and responds with
HTTP 200 and a application/json body with the session token on success;
HTTP 303 redirect to a fresh login flow if the original flow expired with the appropriate error messages set;
HTTP 400 on form validation errors.

Browser flows expect a Content-Type of `application/x-www-form-urlencoded` or `application/json` to be sent in the body and respond with
a HTTP 303 redirect to the post/after login URL or the `return_to` value if it was set and if the login succeeded;
a HTTP 303 redirect to the login UI URL with the flow ID containing the validation errors otherwise.

Browser flows with an accept header of `application/json` will not redirect but instead respond with
HTTP 200 and a application/json body with the signed in identity and a `Set-Cookie` header on success;
HTTP 303 redirect to a fresh login flow if the original flow expired with the appropriate error messages set;
HTTP 400 on form validation errors.

If this endpoint is called with `Accept: application/json` in the header, the response contains the flow without a redirect. In the
case of an error, the `error.id` of the JSON response body can be one of:

`session_already_available`: The user is already signed in.
`security_csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
`security_identity_mismatch`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
`browser_location_change_required`: Usually sent when an AJAX request indicates that the browser needs to open a specific URL.
Most likely used in Social Sign In flows.

More information can be found at [Ory Kratos User Login](https://www.ory.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-registration).

## Query parameters

- `flow` string, required

## Headers

- `X-Session-Token` string

## Request body

- union
  - SubmitSelfServiceLoginFlowWithPasswordMethodBody
    - `csrf_token` string — Sending the anti-csrf token is only required for browser login flows.
    - `identifier` string, required — Identifier is the email or username of the user trying to log in.
    - `method` string, required — Method should be set to "password" when logging in using the identifier and password strategy.
    - `password` string, required — The user's password.
    - `password_identifier` string, required — Identifier is the email or username of the user trying to log in. This field is deprecated!
  - SubmitSelfServiceLoginFlowWithOidcMethodBody — SubmitSelfServiceLoginFlowWithOidcMethodBody is used to decode the login form payload when using the oidc method.
    - `csrf_token` string — The CSRF Token
    - `method` string, required — Method to use This field must be set to `oidc` when using the oidc method.
    - `provider` string, required — The provider to register with
    - `traits` object — The identity traits. This is a placeholder for the registration flow.
  - SubmitSelfServiceLoginFlowWithTotpMethodBody
    - `csrf_token` string — Sending the anti-csrf token is only required for browser login flows.
    - `method` string, required — Method should be set to "totp" when logging in using the TOTP strategy.
    - `totp_code` string, required — The TOTP code.
  - SubmitSelfServiceLoginFlowWithWebAuthnMethodBody
    - `csrf_token` string — Sending the anti-csrf token is only required for browser login flows.
    - `identifier` string — Identifier is the email or username of the user trying to log in. This field is only required when using WebAuthn for passwordless login. When using WebAuthn for multi-factor authentication, it is not needed.
    - `method` string, required — Method should be set to "webAuthn" when logging in using the WebAuthn strategy.
    - `webauthn_login` string — Login a WebAuthn Security Key This must contain the ID of the WebAuthN connection.
  - SubmitSelfServiceLoginFlowWithLookupSecretMethodBody
    - `csrf_token` string — Sending the anti-csrf token is only required for browser login flows.
    - `lookup_secret` string, required — The lookup secret.
    - `method` string, required — Method should be set to "lookup_secret" when logging in using the lookup_secret strategy.

## Response `200`

successfulSelfServiceLoginWithoutBrowser

- SuccessfulSelfServiceLoginWithoutBrowser — The Response for Login Flows via API
  - `session` Session, required — A Session
    - `active` boolean — Active state. If false the session is no longer active.
    - `authenticated_at` string, date-time — The Session Authentication Timestamp When this session was authenticated at. If multi-factor authentication was used this is the time when the last factor was authenticated (e.g. the TOTP code challenge was completed).
    - `authentication_methods` SessionAuthenticationMethod[] — A list of authenticators which were used to authenticate the session.
      - `aal` 'aal0' | 'aal1' | 'aal2' | 'aal3' — The authenticator assurance level can be one of "aal1", "aal2", or "aal3". A higher number means that it is harder for an attacker to compromise the account. Generally, "aal1" implies that one authentication factor was used while AAL2 implies that two factors (e.g. password + TOTP) have been used. To learn more about these levels please head over to: https://www.ory.sh/kratos/docs/concepts/credentials
      - `completed_at` string, date-time — When the authentication challenge was completed.
      - `method` 'link_recovery' | 'password' | 'totp' | 'oidc' | 'webauthn' | 'lookup_secret'
    - `authenticator_assurance_level` 'aal0' | 'aal1' | 'aal2' | 'aal3' — The authenticator assurance level can be one of "aal1", "aal2", or "aal3". A higher number means that it is harder for an attacker to compromise the account. Generally, "aal1" implies that one authentication factor was used while AAL2 implies that two factors (e.g. password + TOTP) have been used. To learn more about these levels please head over to: https://www.ory.sh/kratos/docs/concepts/credentials
    - `expires_at` string, date-time — The Session Expiry When this session expires at.
    - `id` string, uuid4, required
    - `identity` Identity, required — An identity can be a real human, a service, an IoT device - everything that can be described as an "actor" in a system.
      - `created_at` string, date-time — CreatedAt is a helper struct field for gobuffalo.pop.
      - `credentials` object — Credentials represents all credentials that can be used for authenticating this identity.
      - `id` string, uuid4, required
      - `recovery_addresses` RecoveryAddress[] — RecoveryAddresses contains all the addresses that can be used to recover an identity.
        - `created_at` string, date-time — CreatedAt is a helper struct field for gobuffalo.pop.
        - `id` string, uuid4, required
        - `updated_at` string, date-time — UpdatedAt is a helper struct field for gobuffalo.pop.
        - `value` string, required
        - `via` string, required
      - `schema_id` string, required — SchemaID is the ID of the JSON Schema to be used for validating the identity's traits.
      - `schema_url` string, required — SchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from. format: url
      - `state` 'active' | 'inactive' — The state can either be `active` or `inactive`.
      - `state_changed_at` string, date-time
      - `traits` unknown, required
      - `updated_at` string, date-time — UpdatedAt is a helper struct field for gobuffalo.pop.
      - `verifiable_addresses` VerifiableIdentityAddress[] — VerifiableAddresses contains all the addresses that can be verified by the user.
        - `created_at` string, date-time — When this entry was created
        - `id` string, uuid4, required
        - `status` string, required — VerifiableAddressStatus must not exceed 16 characters as that is the limitation in the SQL Schema
        - `updated_at` string, date-time — When this entry was last updated
        - `value` string, required — The address value example foo@user.com
        - `verified` boolean, required — Indicates if the address has already been verified
        - `verified_at` string, date-time
        - `via` string, required — VerifiableAddressType must not exceed 16 characters as that is the limitation in the SQL Schema
    - `issued_at` string, date-time — The Session Issuance Timestamp When this session was issued at. Usually equal or close to `authenticated_at`.
  - `session_token` string — The Session Token A session token is equivalent to a session cookie, but it can be sent in the HTTP Authorization Header: Authorization: bearer ${session-token} The session token is only issued for API flows, not for Browser flows!

## Other responses

- `303` — Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.
- `400` — selfServiceLoginFlow
- `422` — selfServiceBrowserLocationChangeRequiredError
- `500` — jsonError

## Changes

- **2022-03-22** `028a4cf83c15` — 2 breaking, 5 warning, 11 info
  - added the new required request property `oneOf[subschema #1: submitSelfServiceLoginFlowWithPasswordMethodBody is used to decode the login form payload.]/identifier` (media type: application/json)
  - added the new required request property `oneOf[subschema #1: submitSelfServiceLoginFlowWithPasswordMethodBody is used to decode the login form payload.]/identifier` (media type: application/x-www-form-urlencoded)
  - added the new `lookup_secret` enum value to the `active` response property for the response status `400`
  - added the new `lookup_secret` enum value to the `session/authentication_methods/items/method` response property for the response status `200`
  - …14 more
- **2021-12-17** `b793191830a4` — 1 warning
  - added the new `webauthn` enum value to the `session/authentication_methods/items/method` response property for the response status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/ory/apis/ory-identities-api/changes/self-service/login/post.md)

---

[API](https://skmtc.dev/ory/apis/ory-identities-api.md) · [All operations](https://skmtc.dev/ory/apis/ory-identities-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ory/apis/ory-identities-api/revisions/028a4cf83c15?raw)