Skip to main content
The login flow authenticates users using configured authentication methods such as password, social sign-in (OIDC), WebAuthn, or one-time codes.

​
Initialize login flow for browsers

curl -X GET 'https://your-project.projects.oryapis.com/self-service/login/browser' \
  -H 'Accept: application/json'

​
Endpoint

GET /self-service/login/browser
Initializes a browser-based login flow. Sets appropriate cookies and anti-CSRF measures for browser-based flows.

​
Query parameters

​
refresh
boolean
Refresh an existing login session by asking the user to sign in again. Resets the authenticated_at time.
​
aal
string
Request a specific Authenticator Assurance Level. Use aal2 to upgrade a session’s security by requiring multi-factor authentication.
​
return_to
string
URL to redirect the browser to after successful login.
​
login_challenge
string
Hydra login challenge when using Kratos as an OAuth2 identity provider.
​
organization
string
Organization ID for logging in this user (Ory Network only).

​
Response

​
id
string
required
The flow ID, used to fetch and submit the flow.
​
type
string
required
The flow type: browser or api.
​
expires_at
string
required
Time when this flow expires (RFC3339 format).
​
issued_at
string
required
Time when this flow was issued (RFC3339 format).
​
request_url
string
required
The original request URL.
​
ui
object
required
UI container with form fields and messages.
​
created_at
string
When this flow was created.
​
updated_at
string
When this flow was last updated.
​
refresh
boolean
Whether this is a refresh login request.
​
requested_aal
string
The requested Authenticator Assurance Level.

​
Status codes

StatusDescription
200Login flow created (AJAX requests)
303Redirect to login UI with flow ID
400Session already available or other error

​
Initialize login flow for native apps

curl -X GET 'https://your-project.projects.oryapis.com/self-service/login/api' \
  -H 'Accept: application/json'

​
Endpoint

GET /self-service/login/api
Initializes a login flow for native apps. Use this for mobile apps, smart TVs, and other non-browser clients.
Do NOT use this endpoint in browser-based applications. Use /self-service/login/browser instead to prevent CSRF attacks.

​
Query parameters

​
refresh
boolean
Refresh an existing login session.
​
aal
string
Request a specific Authenticator Assurance Level (aal1, aal2, aal3).
​
return_to
string
URL to return to after login completion.
​
return_session_token_exchange_code
boolean
Include a code that can retrieve the session token after login completes.
​
organization
string
Organization ID (Ory Network only).

​
Headers

​
X-Session-Token
string
Session token of the identity performing the login (for AAL2 upgrades).

​
Response

Returns the same login flow object as the browser endpoint.

​
Status codes

StatusDescription
200Login flow created successfully
400Session already available or invalid request

​
Get login flow

curl -X GET 'https://your-project.projects.oryapis.com/self-service/login/flows?id=flow-id' \
  -H 'Accept: application/json'

​
Endpoint

GET /self-service/login/flows
Returns a login flow’s context with error details and other information.

​
Query parameters

​
id
string
required
The login flow ID from the flow URL query parameter.

​
Headers

​
Cookie
string
HTTP Cookie header for browser flows. Required for CSRF validation.

​
Response

Returns the login flow object.

​
Status codes

StatusDescription
200Login flow found
403Forbidden (CSRF violation)
404Flow not found
410Flow expired

​
Submit login flow

curl -X POST 'https://your-project.projects.oryapis.com/self-service/login?flow=flow-id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "method": "password",
    "identifier": "[email protected]",
    "password": "secret-password",
    "csrf_token": "token-from-flow"
  }'

​
Endpoint

POST /self-service/login
Completes a login flow by submitting credentials.

​
Query parameters

​
flow
string
required
The login flow ID.

​
Headers

​
Cookie
string
HTTP Cookie header for browser flows.
​
X-Session-Token
string
Session token for API flows (AAL2 upgrades).

​
Request body

The request body varies by authentication method:
​
method
string
required
Authentication method: password, oidc, webauthn, code, totp, or lookup_secret.
​
csrf_token
string
CSRF token from the flow (required for browser flows).
For password method:
​
identifier
string
required
User’s identifier (email, username, etc.).
​
password
string
required
User’s password.
For OIDC method:
​
provider
string
required
OIDC provider ID (e.g., google, github).
For code method:
​
code
string
required
The one-time code sent to the user.

​
Response (API flows)

​
session
object
required
The created session object.
​
session_token
string
Session token for API clients (store securely).

​
Response (browser flows)

Browser flows return:
  • 303 redirect to the return_to URL or configured post-login URL on success
  • 303 redirect to the login UI with validation errors on failure
  • 200 with JSON if Accept: application/json header is set

​
Status codes

StatusDescription
200Successful login (API flows or AJAX)
303Redirect (browser flows)
400Form validation errors
410Flow expired
422Browser location change required (e.g., OIDC redirect)

​
Error responses

Common error IDs in the response:
  • session_already_available - User is already signed in
  • security_csrf_violation - CSRF token validation failed
  • security_identity_mismatch - The return_to URL is not allowed
  • browser_location_change_required - Browser needs to navigate (OIDC flows)
  • session_aal1_required - Multi-factor auth requested but no session exists

Build docs developers (and LLMs) love

Get started for freeTalk to us