Create Settings Flow for Native Apps

GET 
https://accounts.<domain>/auth/self-service/settings/api

This endpoint initiates a settings flow for API clients such as mobile devices, smart TVs, and so on. You must provide a valid Session Token for this endpoint to respond with HTTP 200 OK.

To fetch an existing settings flow call /settings/flows?flow=<flow_id>.

You MUST NOT use this endpoint in client-side (Single Page Apps, ReactJS, AngularJS) nor server-side (Java Server Pages, NodeJS, PHP, Golang, ...) browser applications. Using this endpoint in these applications will make you vulnerable to a variety of CSRF attacks.

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.

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.

This endpoint MUST ONLY be used in scenarios such as native mobile apps (React Native, Objective C, Swift, Java, ...).

Request

Header Parameters

X-Session-Token string

The Session Token of the Identity performing the settings flow.

Responses

200

settingsFlow

application/json

Schema

Schema

activestring

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
continueWithVerificationUi
actionstringrequired
Action will always be show_verification_ui show_verification_ui ContinueWithActionShowVerificationUIString
Possible values: [show_verification_ui]
flow objectrequired
idstring<uuid>required
The ID of the verification flow
urlstring
The URL of the verification flow
verifiable_addressstringrequired
The address that should be verified in this flow
continueWithSetOrySessionToken
actionstringrequired
Possible values: [set_ory_session_token]
ory_session_tokenstringrequired
Token is the token of the session
continueWithSettingsUi
actionstringrequired
Action will always be show_settings_ui show_settings_ui ContinueWithActionShowSettingsUIString
Possible values: [show_settings_ui]
flow objectrequired
idstring<uuid>required
The ID of the settings flow
continueWithRecoveryUi
actionstringrequired
Action will always be show_recovery_ui show_recovery_ui ContinueWithActionShowRecoveryUIString
Possible values: [show_recovery_ui]
flow objectrequired
idstring<uuid>required
The ID of the recovery flow
urlstring
The URL of the recovery flow
]
expires_atstring<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.

idstring<uuid>required

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_atstring<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
configobject
created_atstring<date-time>
CreatedAt is a helper struct field for gobuffalo.pop.
identifiersstring[]
Identifiers represents a list of unique identifiers this credential type matches.
typeCredentialsType represents several different credential types, like password credentials, passwordless credentials, (string)
and so on.
Possible values: [password, totp, oidc, webauthn, lookup_secret, code]
updated_atstring<date-time>
UpdatedAt is a helper struct field for gobuffalo.pop.
versioninteger<int64>
Version refers to the version of the credential. Useful when changing the config schema.
idstring<uuid>required
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_adminnullJsonRawMessagenullable
NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-
metadata_publicnullJsonRawMessagenullable
NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-
organization_idstring<uuid4>nullable
recovery_addresses object[]
RecoveryAddresses contains all the addresses that can be used to recover an identity.
Array [
created_atstring<date-time>
CreatedAt is a helper struct field for gobuffalo.pop.
idstring<uuid>required
updated_atstring<date-time>
UpdatedAt is a helper struct field for gobuffalo.pop.
valuestringrequired
viaRecoveryAddressType must not exceed 16 characters as that is the limitation in the SQL Schema. (string)required
]
schema_idstringrequired
SchemaID is the ID of the JSON Schema to be used for validating the identity's traits.
schema_urlstringrequired
SchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from.
format: url
stateAn Identity's State (string)
The state can either be active or inactive.
Possible values: [active, inactive]
state_changed_atstring<date-time>
traitsidentityTraitsrequired
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_atstring<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_atstring<date-time>
When this entry was created
Example: 2014-01-01T23:28:56.782Z
idstring<uuid>
The ID
statusidentityVerifiableAddressStatus (string)required
VerifiableAddressStatus must not exceed 16 characters as that is the limitation in the SQL Schema
updated_atstring<date-time>
When this entry was last updated
Example: 2014-01-01T23:28:56.782Z
valuestringrequired
The address value
example foo@user.com
verifiedbooleanrequired
Indicates if the address has already been verified
Example: true
verified_atstring<date-time>
viastringrequired
The delivery method
Possible values: [email, sms]
Example: email
]
issued_atstring<date-time>required

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

request_urlstringrequired

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_tostring

ReturnTo contains the requested return_to URL.

staterequired

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.

typeType is the flow type. (string)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
actionstringrequired
Action should be used as the form action URL <form action="{{ .Action }}" method="post">.
messages object[]
Array [
contextobject
The message's context. Useful when customizing messages.
idinteger<int64>required
textstringrequired
The message text. Written in american english.
typestringrequired
The message type. info Info error Error success Success
Possible values: [info, error, success]
]
methodstringrequired
Method is the form method (e.g. POST)
nodes object[]required
Array [
attributes objectrequired
node_typerequired
Possible values: [a, img, input, script, text]
a
hrefstringrequired
The link's href (destination) URL.
format: uri
idstringrequired
A unique identifier
title objectrequired
contextobject
The message's context. Useful when customizing messages.
idinteger<int64>required
textstringrequired
The message text. Written in american english.
typestringrequired
The message type. info Info error Error success Success
Possible values: [info, error, success]
img
heightinteger<int64>required
Height of the image
idstringrequired
A unique identifier
srcstringrequired
The image's source URL.
format: uri
widthinteger<int64>required
Width of the image
input
autocompletestring
The autocomplete attribute for the input. email InputAttributeAutocompleteEmail tel InputAttributeAutocompleteTel url InputAttributeAutocompleteUrl current-password InputAttributeAutocompleteCurrentPassword new-password InputAttributeAutocompleteNewPassword one-time-code InputAttributeAutocompleteOneTimeCode
Possible values: [email, tel, url, current-password, new-password, one-time-code]
disabledbooleanrequired
Sets the input's disabled field to true or false.
label object
contextobject
The message's context. Useful when customizing messages.
idinteger<int64>required
textstringrequired
The message text. Written in american english.
typestringrequired
The message type. info Info error Error success Success
Possible values: [info, error, success]
namestringrequired
The input's element name.
onclickstring
OnClick may contain javascript which should be executed on click. This is primarily used for WebAuthn.
patternstring
The input's pattern.
requiredboolean
Mark this input field as required.
typestringrequired
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
Possible values: [text, password, number, checkbox, hidden, email, tel, submit, button, datetime-local, date, url]
valuenullable
The input's value.
script
asyncbooleanrequired
The script async type
crossoriginstringrequired
The script cross origin policy
idstringrequired
A unique identifier
integritystringrequired
The script's integrity hash
noncestringrequired
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!
referrerpolicystringrequired
The script referrer policy
srcstringrequired
The script source
typestringrequired
The script MIME type
text
idstringrequired
A unique identifier
text objectrequired
contextobject
The message's context. Useful when customizing messages.
idinteger<int64>required
textstringrequired
The message text. Written in american english.
typestringrequired
The message type. info Info error Error success Success
Possible values: [info, error, success]
groupstringrequired
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
Possible values: [default, password, oidc, profile, link, code, totp, lookup_secret, webauthn]
messages object[]required
Array [
contextobject
The message's context. Useful when customizing messages.
idinteger<int64>required
textstringrequired
The message text. Written in american english.
typestringrequired
The message type. info Info error Error success Success
Possible values: [info, error, success]
]
meta objectrequired
This might include a label and other information that can optionally be used to render UIs.
label object
contextobject
The message's context. Useful when customizing messages.
idinteger<int64>required
textstringrequired
The message text. Written in american english.
typestringrequired
The message type. info Info error Error success Success
Possible values: [info, error, success]
typestringrequired
The node's type text Text input Input img Image a Anchor script Script
Possible values: [text, input, img, a, script]
]

Example (auto)

{
  "active": "string",
  "continue_with": [
    {
      "action": "show_verification_ui",
      "flow": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "url": "string",
        "verifiable_address": "string"
      }
    },
    {
      "action": "set_ory_session_token",
      "ory_session_token": "string"
    },
    {
      "action": "show_settings_ui",
      "flow": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    },
    {
      "action": "show_recovery_ui",
      "flow": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "url": "string"
      }
    }
  ],
  "expires_at": "2024-07-29T15:51:28.071Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "identity": {
    "created_at": "2024-07-29T15:51:28.071Z",
    "credentials": {},
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "organization_id": "string",
    "recovery_addresses": [
      {
        "created_at": "2024-07-29T15:51:28.071Z",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "updated_at": "2024-07-29T15:51:28.071Z",
        "value": "string",
        "via": "string"
      }
    ],
    "schema_id": "string",
    "schema_url": "string",
    "state": "active",
    "state_changed_at": "2024-07-29T15:51:28.071Z",
    "updated_at": "2024-07-29T15:51:28.071Z",
    "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-07-29T15:51:28.071Z",
        "via": "email"
      }
    ]
  },
  "issued_at": "2024-07-29T15:51:28.071Z",
  "request_url": "string",
  "return_to": "string",
  "type": "string",
  "ui": {
    "action": "string",
    "messages": [
      {
        "context": {},
        "id": 0,
        "text": "string",
        "type": "info"
      }
    ],
    "method": "string",
    "nodes": [
      {
        "attributes": {
          "autocomplete": "email",
          "disabled": true,
          "label": {
            "context": {},
            "id": 0,
            "text": "string",
            "type": "info"
          },
          "name": "string",
          "node_type": "string",
          "onclick": "string",
          "pattern": "string",
          "required": true,
          "type": "text"
        },
        "group": "default",
        "messages": [
          {
            "context": {},
            "id": 0,
            "text": "string",
            "type": "info"
          }
        ],
        "meta": {
          "label": {
            "context": {},
            "id": 0,
            "text": "string",
            "type": "info"
          }
        },
        "type": "text"
      }
    ]
  }
}

400

errorGeneric

application/json

Schema

Schema

error objectrequired
codeinteger<int64>
The status code
Example: 404
debugstring
Debug information
This field is often not exposed to protect against leaking sensitive information.
Example: SQL field "foo" is not a bool.
detailsobject
Further error details
idstring
The error ID
Useful when trying to identify various errors in application logic.
messagestringrequired
Error message
The error's message.
Example: The resource could not be found
reasonstring
A human-readable reason for the error
Example: User with ID 1234 does not exist.
requeststring
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
Example: d7ef54b1-ec15-46e6-bccb-524b82c035e6
statusstring
The status description
Example: Not Found

Example (auto)

{
  "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"
  }
}

default

errorGeneric

application/json

Schema

Schema

error objectrequired
codeinteger<int64>
The status code
Example: 404
debugstring
Debug information
This field is often not exposed to protect against leaking sensitive information.
Example: SQL field "foo" is not a bool.
detailsobject
Further error details
idstring
The error ID
Useful when trying to identify various errors in application logic.
messagestringrequired
Error message
The error's message.
Example: The resource could not be found
reasonstring
A human-readable reason for the error
Example: User with ID 1234 does not exist.
requeststring
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
Example: d7ef54b1-ec15-46e6-bccb-524b82c035e6
statusstring
The status description
Example: Not Found

Example (auto)

{
  "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"
  }
}

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://accounts.<domain>/auth/self-service/settings/api");
request.Headers.Add("Accept", "application/json");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request Collapse all

Base URL

https://accounts.<domain>

Parameters

X-Session-Token — header