Settings flow

The settings flow allows authenticated users to manage their account information, credentials, and security settings. Users can update their profile, change passwords, add or remove authentication methods, and configure multi-factor authentication.

Flow initialization

Settings flows require an active authenticated session.

Browser flows

Initialize a settings flow for browser applications:

curl -X GET \
  'https://{project}.projects.oryapis.com/self-service/settings/browser' \
  -H 'Cookie: ory_kratos_session=...' \
  -H 'Accept: application/json'

Query parameters:

return_to - URL to redirect to after successful settings update

Response:

{
  "id": "f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b0c",
  "type": "browser",
  "expires_at": "2026-03-03T12:00:00Z",
  "issued_at": "2026-03-03T11:00:00Z",
  "request_url": "https://{project}.projects.oryapis.com/self-service/settings/browser",
  "ui": {
    "action": "https://{project}.projects.oryapis.com/self-service/settings?flow=f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b0c",
    "method": "POST",
    "nodes": [...]
  },
  "identity": {
    "id": "...",
    "traits": {...}
  },
  "state": "show_form"
}

API flows

For native applications (mobile, desktop, server-to-server):

curl -X GET \
  'https://{project}.projects.oryapis.com/self-service/settings/api' \
  -H 'X-Session-Token: your_session_token' \
  -H 'Accept: application/json'

Settings flows require authentication. If no valid session is present:

Browser flows: Redirect to the login page
API flows: Return 401 Unauthorized

Settings methods

The settings flow supports multiple methods for updating account information.

Profile updates

Update identity traits (email, name, etc.):

curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Token: your_session_token' \
  -d '{
    "method": "profile",
    "traits": {
      "email": "newemail@example.com",
      "name": {
        "first": "Jane",
        "last": "Smith"
      }
    }
  }'

Changing the email address may trigger a verification flow if email verification is enabled.

Password changes

Update the account password:

curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Token: your_session_token' \
  -d '{
    "method": "password",
    "password": "new-secure-password"
  }'

TOTP setup

Enable time-based one-time password authentication:

Initialize TOTP setup

Fetch the settings flow which includes the TOTP QR code:

curl -X GET \
  'https://{project}.projects.oryapis.com/self-service/settings/flows?id=<flow_id>' \
  -H 'X-Session-Token: your_session_token'

The response includes a totp_qr image URL and totp_secret_key.

Verify TOTP code

Submit a code from the authenticator app to confirm setup:

curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Token: your_session_token' \
  -d '{
    "method": "totp",
    "totp_code": "123456"
  }'

Receive backup codes

After successful TOTP setup, backup codes are provided for account recovery.

WebAuthn/Passkey management

Add or remove security keys and passkeys: Add a new passkey:

curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Token: your_session_token' \
  -d '{
    "method": "passkey",
    "passkey_register": "<webauthn_credential>",
    "passkey_display_name": "My iPhone"
  }'

Remove a passkey:

curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Token: your_session_token' \
  -d '{
    "method": "passkey",
    "passkey_remove": "credential_id"
  }'

WebAuthn (security keys)

Manage FIDO2 hardware security keys:

curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Token: your_session_token' \
  -d '{
    "method": "webauthn",
    "webauthn_register": "<webauthn_credential>",
    "webauthn_register_displayname": "YubiKey 5"
  }'

Lookup secrets (backup codes)

Regenerate backup recovery codes:

curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Token: your_session_token' \
  -d '{
    "method": "lookup_secret",
    "lookup_secret_regenerate": true
  }'

OIDC connections

Link or unlink social login providers: Link a provider:

curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Token: your_session_token' \
  -d '{
    "method": "oidc",
    "link": "google"
  }'

Unlink a provider:

curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Token: your_session_token' \
  -d '{
    "method": "oidc",
    "unlink": "google"
  }'

Authenticator assurance levels

Some settings operations may require a higher AAL (Authenticator Assurance Level).

AAL1 required
AAL2 required

Basic authentication with a single factor: profile updates, adding new authentication methods, and linking OIDC providers.

Critical operations requiring MFA: changing password (if AAL2 is configured as required), removing authentication methods, and regenerating backup codes.Configure in your Kratos settings:

selfservice:
  flows:
    settings:
      required_aal: aal2

If the session doesn’t meet the required AAL, the response includes a 403 error directing the user to upgrade their session via a login flow.

Configuration

Configure settings flow behavior:

selfservice:
  flows:
    settings:
      required_aal: aal1
      lifespan: 1h
      ui_url: https://your-app.com/settings
      after:
        default_browser_return_url: https://your-app.com/
        password:
          default_browser_return_url: https://your-app.com/login
          hooks:
            - hook: verify

Fetching an existing flow

Retrieve a settings flow by its ID:

curl -X GET \
  'https://{project}.projects.oryapis.com/self-service/settings/flows?id=<flow_id>' \
  -H 'X-Session-Token: your_session_token'

Error handling

session_inactive
session_aal_not_satisfied
self_service_flow_expired
security_csrf_violation

Status: 401 UnauthorizedNo active session exists.Solution: Redirect to the login flow.

Complete flow example

# 1. Initialize the flow
curl -X GET \
  'https://{project}.projects.oryapis.com/self-service/settings/browser' \
  -H 'Cookie: ory_kratos_session=...'

# Browser is redirected to UI with flow ID
# User visits: https://your-app.com/settings?flow=<flow_id>

# 2. Update password
curl -X POST \
  'https://{project}.projects.oryapis.com/self-service/settings?flow=<flow_id>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Cookie: ory_kratos_session=...' \
  -d 'method=password&password=new-password&csrf_token=...'

# User is redirected to success page

Continuity management

Some settings operations (like changing email) may require interrupting the flow for verification. Kratos uses continuity sessions to maintain state across these interruptions. The continuity key format: ory_kratos_settings_<strategy_id>

API reference

Endpoint	Method	Description
`/self-service/settings/browser`	GET	Initialize browser settings flow
`/self-service/settings/api`	GET	Initialize API settings flow
`/self-service/settings/flows`	GET	Get settings flow by ID
`/self-service/settings`	POST	Submit settings flow

All endpoints are defined in selfservice/flow/settings/handler.go:37-42

Login - Authenticate users
Verification - Verify email changes
Recovery - Reset forgotten passwords

Get Started

Concepts

Self-Service Flows

Authentication Methods

Identity Management

Session Management

Deployment

Security

CLI Reference

Flow initialization

Browser flows

API flows

Settings methods

Profile updates

Password changes

TOTP setup

WebAuthn/Passkey management

WebAuthn (security keys)

Lookup secrets (backup codes)

OIDC connections

Authenticator assurance levels

Configuration

Fetching an existing flow

Error handling

Complete flow example

Continuity management

API reference

Build docs developers (and LLMs) love

Get Started

Concepts

Self-Service Flows

Authentication Methods

Identity Management

Session Management

Deployment

Security

CLI Reference

​Flow initialization

​Browser flows

​API flows

​Settings methods

​Profile updates

​Password changes

​TOTP setup

​WebAuthn/Passkey management

​WebAuthn (security keys)

​Lookup secrets (backup codes)

​OIDC connections

​Authenticator assurance levels

​Configuration

​Fetching an existing flow

​Error handling

​Complete flow example

​Continuity management

​API reference

​Related flows

Build docs developers (and LLMs) love

Flow initialization

Browser flows

API flows

Settings methods

Profile updates

Password changes

TOTP setup

WebAuthn/Passkey management

WebAuthn (security keys)

Lookup secrets (backup codes)

OIDC connections

Authenticator assurance levels

Configuration

Fetching an existing flow

Error handling

Complete flow example

Continuity management

API reference

Related flows