Skip to main content
The Self-Service API enables end-users to manage their own identity lifecycle without administrative intervention. This includes registration, login, account recovery, email verification, profile settings updates, and logout.

​
Browser vs API flows

Ory Kratos supports two distinct flow types optimized for different client environments:

​
Browser flows

Browser flows are designed for web applications that run in a browser environment. These flows:
  • Use HTTP cookies for session management
  • Implement CSRF protection via anti-CSRF tokens and cookies
  • Redirect users to configured UI URLs (e.g., /login, /registration)
  • Set Content-Type: application/x-www-form-urlencoded or application/json
  • Return HTTP 303 redirects on success or validation errors
Initialize browser flows using endpoints like:
  • GET /self-service/login/browser
  • GET /self-service/registration/browser
  • GET /self-service/recovery/browser

​
API flows (native apps)

API flows are designed for native applications without browser access, such as mobile apps, smart TVs, or CLI tools. These flows:
  • Use session tokens instead of cookies
  • Do not require CSRF protection
  • Return JSON responses directly without redirects
  • Accept session tokens via X-Session-Token header
  • Expect Content-Type: application/json
Initialize API flows using endpoints like:
  • GET /self-service/login/api
  • GET /self-service/registration/api
  • GET /self-service/recovery/api
Never use API flow endpoints in browser-based applications (Single Page Apps, server-side rendered apps). This exposes your application to CSRF attacks. Always use browser flow endpoints for web applications.

​
Flow lifecycle

All self-service flows follow a consistent lifecycle:
  1. Initialization - Create a new flow by calling the appropriate endpoint
  2. UI rendering - Display the flow’s UI nodes to the user
  3. Submission - User submits form data to complete the flow
  4. Validation - Kratos validates the submission and returns success or errors
  5. Completion - On success, create session (login/registration) or update state

​
Flow states

Flows contain a state field indicating their current status:
  • choose_method - User needs to select an authentication method
  • sent_email - Verification or recovery email has been sent
  • passed_challenge - User successfully completed a challenge
  • success - Flow completed successfully

​
Flow expiration

All flows have a configurable expiration time (typically 1 hour). After expiration:
  • Accessing the flow returns HTTP 410 Gone
  • Users must initialize a new flow to continue
  • The response includes use_flow_id to reference the replacement flow

​
Authentication methods

Kratos supports multiple authentication methods:
  • Password - Traditional username/password authentication
  • OIDC - Social sign-in with Google, GitHub, etc.
  • WebAuthn - Passwordless authentication with biometrics or security keys
  • Code - One-time codes sent via email or SMS
  • TOTP - Time-based one-time passwords (2FA)
  • Lookup secrets - Recovery codes for 2FA
Browser flows use HTTP-only cookies for session management: 
curl -X GET https://your-project.projects.oryapis.com/self-service/login/browser \
  -H "Cookie: ory_kratos_session=..."
The session cookie is automatically set by Kratos and included in subsequent requests by the browser.

​
Token-based sessions (API flows)

API flows use session tokens passed in the X-Session-Token header: 
curl -X GET https://your-project.projects.oryapis.com/self-service/settings/api \
  -H "X-Session-Token: your-session-token"
Session tokens are returned in successful login/registration responses and must be stored securely by the client.

​
CSRF tokens

Browser flows require CSRF protection. Each flow includes a csrf_token field that must be submitted with form data: 
{
  "method": "password",
  "password": "secret-password",
  "csrf_token": "token-from-flow"
}
CSRF tokens:
  • Are unique per flow
  • Expire with the flow
  • Must be included in all browser flow submissions
  • Are not required for API flows

​
Error handling

Common error codes across self-service flows:
StatusError IDDescription
400session_already_availableUser is already authenticated
400browser_location_change_requiredBrowser needs to navigate to a different URL
403security_csrf_violationCSRF token validation failed
410self_service_flow_expiredFlow has expired, create a new one
422security_identity_mismatchThe return_to URL is not allowed

​
Next steps

Login flow

Authenticate users with password, social sign-in, or passwordless methods

Registration flow

Create new identity accounts with customizable traits

Recovery flow

Enable account recovery via email or other channels

Verification flow

Verify email addresses and phone numbers

Build docs developers (and LLMs) love

Get started for freeTalk to us