---
title: "Complete Settings Flow"
method: POST
path: "/self-service/settings"
tags: ["v0alpha1"]
---

# Complete Settings Flow

`POST /self-service/settings`

Use this endpoint to complete a settings flow by sending an identity's updated password. This endpoint
behaves differently for API and browser flows.

API-initiated flows expect `application/json` to be sent in the body and respond with
HTTP 200 and an application/json body with the session token on success;
HTTP 302 redirect to a fresh settings flow if the original flow expired with the appropriate error messages set;
HTTP 400 on form validation errors.
HTTP 401 when the endpoint is called without a valid session token.
HTTP 403 when `selfservice.flows.settings.privileged_session_max_age` was reached.
Implies that the user needs to re-authenticate.

Browser flows without HTTP Header `Accept` or with `Accept: text/*` respond with
a HTTP 302 redirect to the post/after settings URL or the `return_to` value if it was set and if the flow succeeded;
a HTTP 302 redirect to the Settings UI URL with the flow ID containing the validation errors otherwise.
a HTTP 302 redirect to the login endpoint when `selfservice.flows.settings.privileged_session_max_age` was reached.

Browser flows with HTTP Header `Accept: application/json` respond with
HTTP 200 and a application/json body with the signed in identity and a `Set-Cookie` header on success;
HTTP 302 redirect to a fresh login flow if the original flow expired with the appropriate error messages set;
HTTP 403 when the page is accessed without a session cookie.
HTTP 400 on form validation errors.

More information can be found at [Ory Kratos User Settings & Profile Management Documentation](../self-service/flows/user-settings).

## Query parameters

- `flow` string, required

## Headers

- `X-Session-Token` string

## Request body

- union
  - SubmitSelfServiceSettingsFlowWithPasswordMethodBody
    - `csrf_token` string — CSRFToken is the anti-CSRF token
    - `method` 'password' | 'profile' | 'oidc', required — Method Should be set to password when trying to update a password.
    - `password` string, required — Password is the updated password
  - SubmitSelfServiceSettingsFlowWithProfileMethodBody — nolint:deadcode,unused
    - `csrf_token` string — The Anti-CSRF Token This token is only required when performing browser flows.
    - `method` string, required — Method Should be set to profile when trying to update a profile.
    - `traits` object, required — Traits contains all of the identity's traits.

## Response `200`

successfulSelfServiceSettingsWithoutBrowser

- SuccessfulSelfServiceSettingsWithoutBrowser — The Response for Settings Flows via API
  - `flow` SelfServiceSettingsFlow, required — This flow is used when an identity wants to update settings (e.g. profile data, passwords, ...) in a selfservice manner. We recommend reading the [User Settings Documentation](../self-service/flows/user-settings)
    - `active` string — Active, if set, contains the registration method that is being used. It is initially not set.
    - `expires_at` string, date-time, required — ExpiresAt is the time (UTC) when the flow expires. If the user still wishes to update the setting, a new flow has to be initiated.
    - `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, required — IssuedAt is the time (UTC) when the flow occurred.
    - `request_url` string, required — RequestURL is the initial URL that was requested from Ory Kratos. It can be used to forward information contained in the URL's path or query for example.
    - `state` 'show_form' | 'success', required — show_form: No user data has been collected, or it is invalid, and thus the form should be shown. success: Indicates that the settings flow has been updated successfully with the provided data. Done will stay true when repeatedly checking. If set to true, done will revert back to false only when a flow with invalid (e.g. "please use a valid phone number") data was sent.
    - `type` string — The flow type can either be `api` or `browser`.
    - `ui` UiContainer, required — Container represents a HTML Form. The container can work with both HTTP Form and JSON requests
      - `action` string, required — Action should be used as the form action URL `<form action="{{ .Action }}" method="post">`.
      - `messages` UiText[]
        - `context` object — The message's context. Useful when customizing messages.
        - `id` integer, required
        - `text` string, required — The message text. Written in american english.
        - `type` string, required
      - `method` string, required — Method is the form method (e.g. POST)
      - `nodes` UiNode[], required
        - `attributes` union, required
          - UiNodeInputAttributes — InputAttributes represents the attributes of an input node
            - `disabled` boolean, required — Sets the input's disabled field to true or false.
            - `label` UiText
              - …
            - `name` string, required — The input's element name.
            - `pattern` string — The input's pattern.
            - `required` boolean — Mark this input field as required.
            - `type` string, required
            - `value` unknown
          - UiNodeTextAttributes
            - `text` UiText, required
              - …
          - UiNodeImageAttributes
            - `src` string, required — The image's source URL. format: uri
          - UiNodeAnchorAttributes
            - `href` string, required — The link's href (destination) URL. format: uri
            - `title` UiText, required
              - …
        - `group` string, required
        - `messages` UiText[], required
          - `context` object — The message's context. Useful when customizing messages.
          - `id` integer, required
          - `text` string, required — The message text. Written in american english.
          - `type` string, required
        - `meta` Meta, required — This might include a label and other information that can optionally be used to render UIs.
          - `label` UiText
            - `context` object — The message's context. Useful when customizing messages.
            - `id` integer, required
            - `text` string, required — The message text. Written in american english.
            - `type` string, required
        - `type` string, 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

## Other responses

- `302` — Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.
- `400` — selfServiceSettingsFlow
- `401` — jsonError
- `403` — jsonError
- `500` — jsonError

## Changes

- **2021-07-22** `071bec03ddcd` — 6 breaking, 6 warning
  - the response property `flow/identity/state` became optional for the status `200`
  - the response property `identity/state` became optional for the status `200`
  - the response property `identity/state` became optional for the status `400`
  - the `flow/identity/state` response's property type/format changed from ``/`` to `string`/`` for status `200`
  - …8 more
- **2021-07-13** `8f1b399ab6e6` — 4 breaking, 4 warning, 17 info
  - removed `#/components/schemas/submitSelfServiceSettingsFlowWithPasswordMethod, #/components/schemas/submitSelfServiceSettingsFlowWithProfileMethod` from the request body `oneOf` list (media type: application/json)
  - removed `#/components/schemas/submitSelfServiceSettingsFlowWithPasswordMethod, #/components/schemas/submitSelfServiceSettingsFlowWithProfileMethod` from the request body `oneOf` list (media type: application/x-www-form-urlencoded)
  - the response property `flow/ui/nodes/items/attributes/oneOf[#/components/schemas/uiNodeInputAttributes]/value` became nullable for the status `200`
  - the response property `ui/nodes/items/attributes/oneOf[#/components/schemas/uiNodeInputAttributes]/value` became nullable for the status `400`
  - …21 more
- …earlier changes not shown

[Full history](https://skmtc.dev/ory/apis/ory-identities-api/changes/self-service/settings/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-service-production.skmtc.workers.dev/v1/apis/ory/ory-identities-api/revisions/071bec03ddcd/schema)