Skip to main content

Update Registration Flow

POST 
https://accounts.<domain>/auth/self-service/registration

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

API flows expect application/json to be sent in the body and respond with HTTP 200 and a application/json body with the created identity success - if the session hook is configured the session and session_token will also be included; HTTP 410 if the original flow expired with the appropriate error messages set and optionally a use_flow_id parameter in the body; HTTP 400 on form validation errors.

Browser flows expect a Content-Type of application/x-www-form-urlencoded or application/json to be sent in the body and respond with a HTTP 303 redirect to the post/after registration URL or the return_to value if it was set and if the registration succeeded; a HTTP 303 redirect to the registration UI URL with the flow ID containing the validation errors otherwise.

Browser flows with an accept header of application/json will not redirect but instead 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 400 on form validation errors.

If this endpoint is called with Accept: application/json in the 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_already_available: The user is already signed in. security_csrf_violation: Unable to fetch the flow because a CSRF violation occurred. 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 Registration Flow ID

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

Header Parameters

    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.

Bodyrequired

    methodrequired

    Update Registration Request Body

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

    codestring

    The OTP Code sent to the user

    csrf_tokenstring

    The CSRF Token

    resendstring

    Resend restarts the flow with a new code

    traitsobjectrequired

    The identity's traits

    transient_payloadobject

    Transient data to pass along to any webhooks

Responses​

successfulNativeRegistration

Schema
    continue_with object[]

    Contains a list of actions, that could follow this flow

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

  • Array [
    • oneOf
    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

  • ]
    • 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
  • ]
    • session object

    A Session

    activeboolean

    Active state. If false the session is no longer active.

    authenticated_atstring<date-time>

    The Session Authentication Timestamp

    When this session was authenticated at. If multi-factor authentication was used this is the time when the last factor was authenticated (e.g. the TOTP code challenge was completed).

    authentication_methods object[]

    A list of authenticators which were used to authenticate the session.

  • Array [
    • aalAuthenticator Assurance Level (AAL) (string)

    The authenticator assurance level can be one of "aal1", "aal2", or "aal3". A higher number means that it is harder for an attacker to compromise the account.

    Generally, "aal1" implies that one authentication factor was used while AAL2 implies that two factors (e.g. password + TOTP) have been used.

    Possible values: [aal0, aal1, aal2, aal3]

    completed_atstring<date-time>

    When the authentication challenge was completed.

    methodThe method used (string)

    Possible values: [link_recovery, code_recovery, password, code, totp, oidc, webauthn, lookup_secret, v0.6_legacy_session]

    organizationstring

    The Organization id used for authentication

    providerstring

    OIDC or SAML provider id used for authentication

  • ]
    • authenticator_assurance_levelAuthenticator Assurance Level (AAL) (string)

    The authenticator assurance level can be one of "aal1", "aal2", or "aal3". A higher number means that it is harder for an attacker to compromise the account.

    Generally, "aal1" implies that one authentication factor was used while AAL2 implies that two factors (e.g. password + TOTP) have been used.

    Possible values: [aal0, aal1, aal2, aal3]

    devices object[]

    Devices has history of all endpoints where the session was used

  • Array [
    • idstring<uuid>required

    Device record ID

    ip_addressstring

    IPAddress of the client

    locationstring

    Geo Location corresponding to the IP Address

    user_agentstring

    UserAgent of the client

  • ]
    • expires_atstring<date-time>

    The Session Expiry

    When this session expires at.

    idstring<uuid>required

    Session ID

    identity object

    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>

    The Session Issuance Timestamp

    When this session was issued at. Usually equal or close to authenticated_at.

    tokenizedstring

    Tokenized is the tokenized (e.g. JWT) version of the session.

    It is only set when the tokenize query parameter was set to a valid tokenize template during calls to /session/whoami.

    session_tokenstring

    The Session Token

    This field is only set when the session hook is configured as a post-registration hook.

    A session token is equivalent to a session cookie, but it can be sent in the HTTP Authorization Header:

    Authorization: bearer ${session-token}

    The session token is only issued for API flows, not for Browser flows!

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://accounts.<domain>/auth/self-service/registration");
request.Headers.Add("Accept", "application/json");
var content = new StringContent("{\n  \"csrf_token\": \"string\",\n  \"method\": \"string\",\n  \"password\": \"string\",\n  \"traits\": {},\n  \"transient_payload\": {}\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Request Collapse all
Base URL
https://accounts.<domain>
Parameters
— queryrequired
— header
Body required
{
  "csrf_token": "string",
  "method": "string",
  "password": "string",
  "traits": {},
  "transient_payload": {}
}