Skip to main content
The settings flow enables authenticated users to update their profile information, change passwords, add/remove authentication methods, and manage their account settings.
The settings flow requires an active session. Unauthenticated users will be redirected to login.

​
Initialize settings flow for browsers

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

​
Endpoint

GET /self-service/settings/browser
Initializes a browser-based settings flow. Requires a valid session cookie.

​
Query parameters

​
return_to
string
URL to redirect the browser to after successful settings update.

​
Headers

​
Cookie
string
required
Session cookie for authentication. If missing or invalid, redirects to login.

​
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.
​
identity
object
required
The current identity with traits and credentials.
​
state
string
required
Current state of the flow (e.g., show_form, success).

​
Status codes

StatusDescription
200Settings flow created (AJAX requests)
303Redirect to settings UI or login
401No active session
403Session AAL too low (requires re-authentication)

​
Initialize settings flow for native apps

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

​
Endpoint

GET /self-service/settings/api
Initializes a settings flow for native apps. Requires a valid session token.
Do NOT use this endpoint in browser-based applications. Use /self-service/settings/browser instead to prevent CSRF attacks.

​
Headers

​
X-Session-Token
string
required
Session token for authentication. Returns 401 if missing or invalid.

​
Response

Returns the same settings flow object as the browser endpoint.

​
Status codes

StatusDescription
200Settings flow created successfully
400Invalid request
401Invalid or missing session token
403Session AAL too low

​
Get settings flow

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

​
Endpoint

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

​
Query parameters

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

​
Headers

​
Cookie
string
Session cookie for browser flows.
​
X-Session-Token
string
Session token for API flows.

​
Response

Returns the settings flow object.

​
Status codes

StatusDescription
200Settings flow found
401No active session
403Session AAL too low or CSRF violation
404Flow not found
410Flow expired

​
Submit settings flow

The settings flow supports multiple update methods:

​
Update profile traits

curl -X POST 'https://your-project.projects.oryapis.com/self-service/settings?flow=flow-id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-Session-Token: your-session-token' \
  -d '{
    "method": "profile",
    "traits": {
      "email": "[email protected]",
      "name": "Jane Doe"
    },
    "csrf_token": "token-from-flow"
  }'

​
Update password

curl -X POST 'https://your-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",
    "csrf_token": "token-from-flow"
  }'

​
Add TOTP authenticator

curl -X POST 'https://your-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",
    "csrf_token": "token-from-flow"
  }'

​
Add WebAuthn device

curl -X POST 'https://your-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": "credential-data",
    "webauthn_register_displayname": "YubiKey 5C",
    "csrf_token": "token-from-flow"
  }'

curl -X POST 'https://your-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",
    "csrf_token": "token-from-flow"
  }'

​
Endpoint

POST /self-service/settings
Completes a settings flow by updating the identity.

​
Query parameters

​
flow
string
required
The settings flow ID.

​
Headers

​
Cookie
string
Session cookie for browser flows.
​
X-Session-Token
string
Session token for API flows.

​
Request body

The request body varies by method:
​
method
string
required
Settings method: profile, password, totp, webauthn, oidc, or lookup_secret.
​
csrf_token
string
CSRF token from the flow (required for browser flows).
For profile method:
​
traits
object
required
Updated identity traits (email, name, etc.).
For password method:
​
password
string
required
New password. Must meet configured password policy.
For TOTP method:
​
totp_code
string
required
TOTP code from authenticator app to confirm setup.
​
totp_unlink
boolean
Set to true to remove TOTP.
For WebAuthn method:
​
webauthn_register
string
WebAuthn credential from navigator.credentials.create().
​
webauthn_register_displayname
string
Display name for the WebAuthn device.
​
webauthn_remove
string
Credential ID to remove.
For OIDC method:
​
link
string
OIDC provider ID to link.
​
unlink
string
OIDC provider ID to unlink.

​
Response

​
identity
object
required
Updated identity object with new traits/credentials.
​
state
string
required
Flow state (typically success after successful update).
​
ui
object
required
Updated UI with success messages or validation errors.

​
Response (browser flows)

Browser flows return:
  • 303 redirect to the return_to URL or settings UI on success
  • 303 redirect to login if session expired or AAL too low
  • 200 with JSON if Accept: application/json header is set

​
Status codes

StatusDescription
200Settings updated successfully
303Redirect (browser flows)
400Form validation errors
401No active session
403Session AAL too low or privileged session required
410Flow expired
422Browser location change required (OIDC linking)

​
Privileged sessions

Some settings operations require a “privileged session” - a session where the user recently re-authenticated. This is configured via selfservice.flows.settings.privileged_session_max_age. If the session is too old:
  • Browser flows redirect to login with ?refresh=true
  • API flows return HTTP 403 with error details

​
Authenticator Assurance Levels (AAL)

If your identity has multi-factor credentials (e.g., password + TOTP), but the current session only used single-factor authentication (AAL1), you may receive a 403 error. To resolve:
  • Request AAL2 by initiating a login flow with ?aal=aal2
  • Complete the second factor authentication
  • Retry the settings update

​
Error responses

Common error IDs:
  • session_inactive - No active session, user needs to log in
  • session_aal2_required - Multi-factor authentication required
  • session_refresh_required - Session too old, re-authentication required
  • security_csrf_violation - CSRF token validation failed
  • security_identity_mismatch - Identity changed during flow

Build docs developers (and LLMs) love

Get started for freeTalk to us