Skip to main content

Complete Settings Flow

POST 
/auth/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 303 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 or the session's AAL is too low. Implies that the user needs to re-authenticate.

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

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 303 redirect to a fresh login flow if the original flow expired with the appropriate error messages set; HTTP 401 when the endpoint is called without a valid session cookie. HTTP 403 when the page is accessed without a session cookie or the session's AAL is too low. HTTP 400 on form validation errors.

Depending on your configuration this endpoint might return a 403 error if the session has a lower Authenticator Assurance Level (AAL) than is possible for the identity. This can happen if the identity has password + webauthn credentials (which would result in AAL2) but the session has only AAL1. If this error occurs, ask the user to sign in with the second factor (happens automatically for server-side browser flows) or change the configuration.

If this endpoint is called with a Accept: application/json HTTP header, the response contains the flow without a redirect. In the case of an error, the error.id of the JSON response body can be one of:

session_refresh_required: The identity requested to change something that needs a privileged session. Redirect the identity to the login init endpoint with query parameters ?refresh=true&return_to=<the-current-browser-url>, or initiate a refresh login flow otherwise. security_csrf_violation: Unable to fetch the flow because a CSRF violation occurred. session_inactive: No Session was found - sign in a user first. security_identity_mismatch: The flow was interrupted with session_refresh_required but apparently some other identity logged in instead. security_identity_mismatch: The requested ?return_to address is not allowed to be used. Adjust this in the configuration! browser_location_change_required: Usually sent when an AJAX request indicates that the browser needs to open a specific URL. Most likely used in Social Sign In flows.

Request​

Query Parameters

    flow stringrequired

    The Settings Flow ID

    The value for this parameter comes from flow URL Query parameter sent to your application (e.g. /settings?flow=abcde).

Header Parameters

    X-Session-Token string

    The Session Token of the Identity performing the settings flow.

    Cookie string

    HTTP Cookies

    When using the SDK in a browser app, on the server side you must include the HTTP Cookie Header sent by the client to your server here. This ensures that CSRF and session cookies are respected.

Body

required
    oneOf
    csrf_token string

    CSRFToken is the anti-CSRF token

    method stringrequired

    Method

    Should be set to password when trying to update a password.

    password stringrequired

    Password is the updated password

Responses​

settingsFlow

Schema
    active string

    Active, if set, contains the registration method that is being used. It is initially not set.

    continue_with object[]

    Contains a list of actions, that could follow this flow

    It can, for example, contain a reference to the verification flow, created as part of the user's registration.

  • Array [
    • oneOf
    action stringrequired

    Possible values: [show_verification_ui]

    Action will always be show_verification_ui show_verification_ui ContinueWithActionShowVerificationUIString

    flow objectrequired
    id uuidrequired

    The ID of the verification flow

    url string

    The URL of the verification flow

    verifiable_address stringrequired

    The address that should be verified in this flow

  • ]
    • expires_at date-timerequired

    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 uuidrequired

    ID represents the flow's unique ID. When performing the settings flow, this represents the id in the settings ui's query parameter: http://<selfservice.flows.settings.ui_url>?flow=

    identity objectrequired

    An identity represents a (human) user.

    created_at 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.

    property name* identityCredentials

    Credentials represents a specific credential type

    config object
    created_at date-time

    CreatedAt is a helper struct field for gobuffalo.pop.

    identifiers string[]

    Identifiers represents a list of unique identifiers this credential type matches.

    type CredentialsType represents several different credential types, like password credentials, passwordless credentials,

    Possible values: [password, totp, oidc, webauthn, lookup_secret, code]

    and so on.

    updated_at date-time

    UpdatedAt is a helper struct field for gobuffalo.pop.

    version int64

    Version refers to the version of the credential. Useful when changing the config schema.

    id uuidrequired

    ID is the identity's unique identifier.

    The Identity ID can not be changed and can not be chosen. This ensures future compatibility and optimization for distributed stores such as CockroachDB.

    metadata_admin nullJsonRawMessagenullable

    NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-

    metadata_public nullJsonRawMessagenullable

    NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-

    organization_id uuid4nullable
    recovery_addresses object[]

    RecoveryAddresses contains all the addresses that can be used to recover an identity.

  • Array [
    • created_at date-time

    CreatedAt is a helper struct field for gobuffalo.pop.

    id uuidrequired
    updated_at date-time

    UpdatedAt is a helper struct field for gobuffalo.pop.

    value stringrequired
    via RecoveryAddressType must not exceed 16 characters as that is the limitation in the SQL Schema.required
  • ]
    • schema_id stringrequired

    SchemaID is the ID of the JSON Schema to be used for validating the identity's traits.

    schema_url stringrequired

    SchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from.

    format: url

    state An Identity's State

    Possible values: [active, inactive]

    The state can either be active or inactive.

    state_changed_at date-time
    traits identityTraitsrequired

    Traits represent an identity's traits. The identity is able to create, modify, and delete traits in a self-service manner. The input will always be validated against the JSON Schema defined in schema_url.

    updated_at date-time

    UpdatedAt is a helper struct field for gobuffalo.pop.

    verifiable_addresses object[]

    VerifiableAddresses contains all the addresses that can be verified by the user.

  • Array [
    • created_at date-time

    When this entry was created

    id uuid

    The ID

    status identityVerifiableAddressStatusrequired

    VerifiableAddressStatus must not exceed 16 characters as that is the limitation in the SQL Schema

    updated_at date-time

    When this entry was last updated

    value stringrequired

    The address value

    example foo@user.com

    verified booleanrequired

    Indicates if the address has already been verified

    verified_at date-time
    via stringrequired

    Possible values: [email, sms]

    The delivery method

  • ]
    • issued_at date-timerequired

    IssuedAt is the time (UTC) when the flow occurred.

    request_url stringrequired

    RequestURL is the initial URL that was requested. It can be used to forward information contained in the URL's path or query for example.

    return_to string

    ReturnTo contains the requested return_to URL.

    state required

    State represents the state of this flow. It knows two states:

    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 Type is the flow type.required

    The flow type can either be api or browser.

    ui objectrequired

    Container represents a HTML Form. The container can work with both HTTP Form and JSON requests

    action stringrequired

    Action should be used as the form action URL <form action="{{ .Action }}" method="post">.

    messages object[]
  • Array [
    • context object

    The message's context. Useful when customizing messages.

    id int64required
    text stringrequired

    The message text. Written in american english.

    type stringrequired

    Possible values: [info, error, success]

    The message type. info Info error Error success Success

  • ]
    • method stringrequired

    Method is the form method (e.g. POST)

    nodes object[]required
  • Array [
    • attributes objectrequired
    oneOf
    autocomplete string

    Possible values: [email, tel, url, current-password, new-password, one-time-code]

    The autocomplete attribute for the input. email InputAttributeAutocompleteEmail tel InputAttributeAutocompleteTel url InputAttributeAutocompleteUrl current-password InputAttributeAutocompleteCurrentPassword new-password InputAttributeAutocompleteNewPassword one-time-code InputAttributeAutocompleteOneTimeCode

    disabled booleanrequired

    Sets the input's disabled field to true or false.

    label object
    context object

    The message's context. Useful when customizing messages.

    id int64required
    text stringrequired

    The message text. Written in american english.

    type stringrequired

    Possible values: [info, error, success]

    The message type. info Info error Error success Success

    name stringrequired

    The input's element name.

    node_type stringrequired

    NodeType represents this node's types. It is a mirror of node.type and is primarily used to allow compatibility with OpenAPI 3.0. In this struct it technically always is "input".

    onclick string

    OnClick may contain javascript which should be executed on click. This is primarily used for WebAuthn.

    pattern string

    The input's pattern.

    required boolean

    Mark this input field as required.

    type stringrequired

    Possible values: [text, password, number, checkbox, hidden, email, tel, submit, button, datetime-local, date, url]

    The input's element type. text InputAttributeTypeText password InputAttributeTypePassword number InputAttributeTypeNumber checkbox InputAttributeTypeCheckbox hidden InputAttributeTypeHidden email InputAttributeTypeEmail tel InputAttributeTypeTel submit InputAttributeTypeSubmit button InputAttributeTypeButton datetime-local InputAttributeTypeDateTimeLocal date InputAttributeTypeDate url InputAttributeTypeURI

    value nullable

    The input's value.

    group stringrequired

    Possible values: [default, password, oidc, profile, link, code, totp, lookup_secret, webauthn]

    Group specifies which group (e.g. password authenticator) this node belongs to. default DefaultGroup password PasswordGroup oidc OpenIDConnectGroup profile ProfileGroup link LinkGroup code CodeGroup totp TOTPGroup lookup_secret LookupGroup webauthn WebAuthnGroup

    messages object[]required
  • Array [
    • context object

    The message's context. Useful when customizing messages.

    id int64required
    text stringrequired

    The message text. Written in american english.

    type stringrequired

    Possible values: [info, error, success]

    The message type. info Info error Error success Success

  • ]
    • meta objectrequired

    This might include a label and other information that can optionally be used to render UIs.

    label object
    context object

    The message's context. Useful when customizing messages.

    id int64required
    text stringrequired

    The message text. Written in american english.

    type stringrequired

    Possible values: [info, error, success]

    The message type. info Info error Error success Success

    type stringrequired

    Possible values: [text, input, img, a, script]

    The node's type text Text input Input img Image a Anchor script Script

  • ]
Loading...