Get Settings Flow
GET/auth/self-service/settings/flows
When accessing this endpoint you must ensure that either the Session Cookie or the Session Token are set.
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 or change the configuration.
If this endpoint is called via an AJAX request, 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:
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.
Request
Query Parameters
ID is 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
The Session Token
When using the SDK in an app without a browser, please include the session token here.
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.
Responses
- 200
- 401
- 403
- 404
- 410
- default
settingsFlow
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- continueWithVerificationUi
- continueWithSetOrySessionToken
- continueWithSettingsUi
- continueWithRecoveryUi
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- uiNodeInputAttributes
- TextAttributes represents the attributes of a text node.
- ImageAttributes represents the attributes of an image node.
- AnchorAttributes represents the attributes of an anchor node.
- ScriptAttributes represent script nodes which load javascript.
- Array [
- ]
- ]
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.
Possible values: [show_verification_ui
]
Action will always be show_verification_ui
show_verification_ui ContinueWithActionShowVerificationUIString
flow objectrequired
The ID of the verification flow
The URL of the verification flow
The address that should be verified in this flow
Possible values: [set_ory_session_token
]
Token is the token of the session
Possible values: [show_settings_ui
]
Action will always be show_settings_ui
show_settings_ui ContinueWithActionShowSettingsUIString
flow objectrequired
The ID of the settings flow
Possible values: [show_recovery_ui
]
Action will always be show_recovery_ui
show_recovery_ui ContinueWithActionShowRecoveryUIString
flow objectrequired
The ID of the recovery flow
The URL of the recovery flow
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 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.
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
CreatedAt is a helper struct field for gobuffalo.pop.
Identifiers represents a list of unique identifiers this credential type matches.
Possible values: [password
, totp
, oidc
, webauthn
, lookup_secret
, code
]
and so on.
UpdatedAt is a helper struct field for gobuffalo.pop.
Version refers to the version of the credential. Useful when changing the config schema.
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.
NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-
NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-
recovery_addresses object[]
RecoveryAddresses contains all the addresses that can be used to recover an identity.
CreatedAt is a helper struct field for gobuffalo.pop.
UpdatedAt is a helper struct field for gobuffalo.pop.
SchemaID is the ID of the JSON Schema to be used for validating the identity's traits.
SchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from.
format: url
Possible values: [active
, inactive
]
The state can either be active
or inactive
.
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
.
UpdatedAt is a helper struct field for gobuffalo.pop.
verifiable_addresses object[]
VerifiableAddresses contains all the addresses that can be verified by the user.
When this entry was created
The ID
VerifiableAddressStatus must not exceed 16 characters as that is the limitation in the SQL Schema
When this entry was last updated
The address value
example foo@user.com
Indicates if the address has already been verified
Possible values: [email
, sms
]
The delivery method
IssuedAt is the time (UTC) when the flow occurred.
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.
ReturnTo contains the requested return_to URL.
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.
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 should be used as the form action URL <form action="{{ .Action }}" method="post">
.
messages object[]
The message's context. Useful when customizing messages.
The message text. Written in american english.
Possible values: [info
, error
, success
]
The message type. info Info error Error success Success
Method is the form method (e.g. POST)
nodes object[]required
attributes objectrequired
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
Sets the input's disabled field to true or false.
label object
The message's context. Useful when customizing messages.
The message text. Written in american english.
Possible values: [info
, error
, success
]
The message type. info Info error Error success Success
The input's element name.
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 may contain javascript which should be executed on click. This is primarily used for WebAuthn.
The input's pattern.
Mark this input field as required.
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
The input's value.
A unique identifier
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 "text".
text objectrequired
The message's context. Useful when customizing messages.
The message text. Written in american english.
Possible values: [info
, error
, success
]
The message type. info Info error Error success Success
Height of the image
A unique identifier
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 "img".
The image's source URL.
format: uri
Width of the image
The link's href (destination) URL.
format: uri
A unique identifier
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 "a".
title objectrequired
The message's context. Useful when customizing messages.
The message text. Written in american english.
Possible values: [info
, error
, success
]
The message type. info Info error Error success Success
The script async type
The script cross origin policy
A unique identifier
The script's integrity hash
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 "script".
Nonce for CSP
A nonce you may want to use to improve your Content Security Policy. You do not have to use this value but if you want to improve your CSP policies you may use it. You can also choose to use your own nonce value!
The script referrer policy
The script source
The script MIME type
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
The message's context. Useful when customizing messages.
The message text. Written in american english.
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
The message's context. Useful when customizing messages.
The message text. Written in american english.
Possible values: [info
, error
, success
]
The message type. info Info error Error success Success
Possible values: [text
, input
, img
, a
, script
]
The node's type text Text input Input img Image a Anchor script Script
{
"active": "string",
"continue_with": [
{},
{},
{},
{}
],
"expires_at": "2024-03-30T07:38:31.802Z",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"identity": {
"created_at": "2024-03-30T07:38:31.802Z",
"credentials": {},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organization_id": "string",
"recovery_addresses": [
{
"created_at": "2024-03-30T07:38:31.802Z",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"updated_at": "2024-03-30T07:38:31.802Z",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"state": "active",
"state_changed_at": "2024-03-30T07:38:31.802Z",
"updated_at": "2024-03-30T07:38:31.802Z",
"verifiable_addresses": [
{
"created_at": "2014-01-01T23:28:56.782Z",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"updated_at": "2014-01-01T23:28:56.782Z",
"value": "string",
"verified": true,
"verified_at": "2024-03-30T07:38:31.802Z",
"via": "email"
}
]
},
"issued_at": "2024-03-30T07:38:31.802Z",
"request_url": "string",
"return_to": "string",
"type": "string",
"ui": {
"action": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "info"
}
],
"method": "string",
"nodes": [
{
"attributes": {},
"group": "default",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "info"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "info"
}
},
"type": "text"
}
]
}
}
errorGeneric
- application/json
- Schema
- Example (from schema)
Schema
error objectrequired
The status code
Debug information
This field is often not exposed to protect against leaking sensitive information.
details object
Further error details
The error ID
Useful when trying to identify various errors in application logic.
Error message
The error's message.
A human-readable reason for the error
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
The status description
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"id": "string",
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}
errorGeneric
- application/json
- Schema
- Example (from schema)
Schema
error objectrequired
The status code
Debug information
This field is often not exposed to protect against leaking sensitive information.
details object
Further error details
The error ID
Useful when trying to identify various errors in application logic.
Error message
The error's message.
A human-readable reason for the error
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
The status description
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"id": "string",
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}
errorGeneric
- application/json
- Schema
- Example (from schema)
Schema
error objectrequired
The status code
Debug information
This field is often not exposed to protect against leaking sensitive information.
details object
Further error details
The error ID
Useful when trying to identify various errors in application logic.
Error message
The error's message.
A human-readable reason for the error
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
The status description
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"id": "string",
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}
errorGeneric
- application/json
- Schema
- Example (from schema)
Schema
error objectrequired
The status code
Debug information
This field is often not exposed to protect against leaking sensitive information.
details object
Further error details
The error ID
Useful when trying to identify various errors in application logic.
Error message
The error's message.
A human-readable reason for the error
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
The status description
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"id": "string",
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}
errorGeneric
- application/json
- Schema
- Example (from schema)
Schema
error objectrequired
The status code
Debug information
This field is often not exposed to protect against leaking sensitive information.
details object
Further error details
The error ID
Useful when trying to identify various errors in application logic.
Error message
The error's message.
A human-readable reason for the error
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
The status description
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"id": "string",
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}