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

# 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 expect `application/x-www-form-urlencoded` to be sent in the body and responds 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.

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
  - SubmitSelfServiceSettingsFlowWithPasswordMethod
    - `csrf_token` string — CSRFToken is the anti-CSRF token type: string
    - `method` string — Method Should be set to password when trying to update a password. type: string
    - `password` string, required — Password is the updated password type: string
  - SubmitSelfServiceSettingsFlowWithProfileMethod — nolint:deadcode,unused
    - `csrf_token` string — The Anti-CSRF Token This token is only required when performing browser flows.
    - `method` string — Method Should be set to profile when trying to update a profile. type: string
    - `traits` object, required — Traits contains all of the identity's traits.

## Response `200`

settingsViaApiResponse

- SettingsViaApiResponse — The Response for Settings Flows via API
  - `flow` SettingsFlow, 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.
      - `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
      - `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` string, required
    - `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` union
              - …
          - 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.
    - `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
    - `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` — settingsFlow
- `401` — jsonError
- `403` — jsonError
- `500` — jsonError

## Changes

- **2021-05-18** `9123bcead5ed` — 3 breaking, 25 info
  - the `flow/identity/traits` response's property type changed from `object` to no type for status `200`
  - the `identity/traits` response's property type changed from `object` to no type for status `200`
  - the `identity/traits` response's property type changed from `object` to no type for status `400`
  - added the new optional `header` request parameter `X-Session-Token`
  - …24 more
- **2021-05-11** `0b5d5b421f15` — 3 warning
  - removed the optional property `flow/identity/test` from the response with the `200` status
  - removed the optional property `identity/test` from the response with the `200` status
  - removed the optional property `identity/test` from the response with the `400` status
- **2021-05-10** `8b8f8cf57b16` — 3 info
  - added the optional property `flow/identity/test` to the response with the `200` status
  - added the optional property `identity/test` to the response with the `200` status
  - added the optional property `identity/test` to the response with the `400` status
- …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/9123bcead5ed/schema)