Skip to main content

Update Registration Flow

POST 
/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.

Body

required
    oneOf
    csrf_token string

    The CSRF Token

    method stringrequired

    Method to use

    This field must be set to password when using the password method.

    password stringrequired

    Password to sign the user up with

    traits objectrequired

    The identity's traits

    transient_payload object

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

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

  • ]
    • session object

    A Session

    active boolean

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

    authenticated_at 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 [
    • aal Authenticator Assurance Level (AAL)

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

    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.

    completed_at date-time

    When the authentication challenge was completed.

    method The method used

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

    organization string

    The Organization id used for authentication

    provider string

    OIDC or SAML provider id used for authentication

  • ]
    • authenticator_assurance_level Authenticator Assurance Level (AAL)

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

    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.

    devices object[]

    Devices has history of all endpoints where the session was used

  • Array [
    • id uuidrequired

    Device record ID

    ip_address string

    IPAddress of the client

    location string

    Geo Location corresponding to the IP Address

    user_agent string

    UserAgent of the client

  • ]
    • expires_at date-time

    The Session Expiry

    When this session expires at.

    id uuidrequired

    Session ID

    identity object

    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-time

    The Session Issuance Timestamp

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

    tokenized string

    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_token string

    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!

Loading...