Registration flow API

The registration flow allows users to create new accounts. It supports multiple registration methods including password, social sign-in (OIDC), WebAuthn, and one-time codes.

Initialize registration flow for browsers

curl -X GET 'https://your-project.projects.oryapis.com/self-service/registration/browser' \
  -H 'Accept: application/json'

Endpoint

GET /self-service/registration/browser

Initializes a browser-based registration flow. Sets cookies and anti-CSRF measures for browser-based flows.

Query parameters

return_to

string

URL to redirect the browser to after successful registration.

Hydra login challenge when using Kratos with OAuth2/OIDC.

after_verification_return_to

string

URL to redirect to after completing email verification (overrides default verification redirect).

organization

string

Organization ID to register this user with (Ory Network only).

identity_schema

string

Identity schema ID to use for this registration flow.

Response

string

required

The flow ID, used to fetch and submit the flow.

type

string

required

The flow type: browser or api.

expires_at

string

required

Time when this flow expires (RFC3339 format).

issued_at

string

required

Time when this flow was issued (RFC3339 format).

request_url

string

required

The original request URL.

object

required

UI container with form fields and messages.

Show ui object

action

string

required

The form action URL where the flow should be submitted.

method

string

required

HTTP method for form submission (typically POST).

nodes

array

required

Form fields, buttons, and other UI elements to render. Includes trait fields like email, name, etc.

messages

array

Global messages to display.

OAuth2 login challenge if applicable.

organization_id

string

Organization ID for this registration.

Status codes

Status	Description
200	Registration flow created (AJAX requests)
303	Redirect to registration UI with flow ID
400	Session already available

Initialize registration flow for native apps

curl -X GET 'https://your-project.projects.oryapis.com/self-service/registration/api' \
  -H 'Accept: application/json'

Endpoint

GET /self-service/registration/api

Initializes a registration flow for native apps. Use this for mobile apps, smart TVs, and other non-browser clients.

Do NOT use this endpoint in browser-based applications. Use /self-service/registration/browser instead to prevent CSRF attacks.

Query parameters

return_to

string

URL to return to after registration completion.

return_session_token_exchange_code

boolean

Include a code that can retrieve the session token after registration.

organization

string

Organization ID (Ory Network only).

identity_schema

string

Identity schema ID to use.

Response

Returns the same registration flow object as the browser endpoint.

Status codes

Status	Description
200	Registration flow created successfully
400	Invalid request or session already exists

Get registration flow

curl -X GET 'https://your-project.projects.oryapis.com/self-service/registration/flows?id=flow-id' \
  -H 'Accept: application/json'

Endpoint

GET /self-service/registration/flows

Returns a registration flow’s context with error details and other information.

Query parameters

string

required

The registration flow ID from the flow URL query parameter.

Headers

HTTP Cookie header for browser flows. Required for CSRF validation.

Response

Returns the registration flow object.

Status codes

Status	Description
200	Registration flow found
403	Forbidden (CSRF violation)
404	Flow not found
410	Flow expired

Submit registration flow

curl -X POST 'https://your-project.projects.oryapis.com/self-service/registration?flow=flow-id' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "method": "password",
    "password": "secure-password",
    "traits": {
      "email": "[email protected]",
      "name": "John Doe"
    },
    "csrf_token": "token-from-flow"
  }'

Endpoint

POST /self-service/registration

Completes a registration flow by creating a new identity.

Query parameters

flow

string

required

The registration flow ID.

Headers

HTTP Cookie header for browser flows.

Request body

The request body varies by registration method:

method

string

required

Registration method: password, oidc, webauthn, or code.

traits

object

required

Identity traits (email, name, etc.) as defined in your identity schema.

csrf_token

string

CSRF token from the flow (required for browser flows).

For password method:

password

string

required

The user’s password. Must meet configured password policy requirements.

For OIDC method:

provider

string

required

OIDC provider ID (e.g., google, github, microsoft).

For WebAuthn method:

webauthn_register

string

required

WebAuthn credential data from navigator.credentials.create().

webauthn_register_displayname

string

Display name for the WebAuthn credential.

For code method:

code

string

required

The one-time registration code.

Response (API flows)

identity

object

required

The created identity object.

Show identity object

string

required

Identity ID (UUID).

schema_id

string

required

The identity schema ID.

schema_url

string

required

URL to fetch the identity schema.

traits

object

required

Identity traits (email, name, etc.).

verifiable_addresses

array

Email addresses and phone numbers that can be verified.

recovery_addresses

array

Addresses that can be used for account recovery.

state

string

Identity state: active or inactive.

session

object

The created session (if session hook is configured).

Show session object

string

required

Session ID.

active

boolean

required

Whether the session is active.

identity

object

required

The authenticated identity.

session_token

string

Session token for API clients (if session hook is configured).

continue_with

array

Actions to continue with after registration (e.g., verification flow).

Response (browser flows)

Browser flows return:

303 redirect to the return_to URL or configured post-registration URL on success
303 redirect to the registration UI with validation errors on failure
200 with JSON if Accept: application/json header is set

Status codes

Status	Description
200	Successful registration (API flows)
303	Redirect (browser flows)
400	Form validation errors
410	Flow expired
422	Browser location change required (e.g., OIDC redirect)

Error responses

Common error IDs in the response:

session_already_available - User is already signed in
security_csrf_violation - CSRF token validation failed
security_identity_mismatch - The return_to URL is not allowed
browser_location_change_required - Browser needs to navigate (OIDC flows)

Validation errors appear in the ui.nodes array with error messages for specific fields.

Admin API

Self-Service API

Frontend API

Registration flow API

Initialize registration flow for browsers

Endpoint

Query parameters

Response

Status codes

Initialize registration flow for native apps

Endpoint

Query parameters

Response

Status codes

Get registration flow

Endpoint

Query parameters

Headers

Response

Status codes

Submit registration flow

Endpoint

Query parameters

Headers

Request body

Response (API flows)

Response (browser flows)

Status codes

Error responses

Build docs developers (and LLMs) love

Admin API

Self-Service API

Frontend API

​Initialize registration flow for browsers

​Endpoint

​Query parameters

​Response

​Status codes

​Initialize registration flow for native apps

​Endpoint

​Query parameters

​Response

​Status codes

​Get registration flow

​Endpoint

​Query parameters

​Headers

​Response

​Status codes

​Submit registration flow

​Endpoint

​Query parameters

​Headers

​Request body

​Response (API flows)

​Response (browser flows)

​Status codes

​Error responses

Build docs developers (and LLMs) love

Initialize registration flow for browsers

Endpoint

Query parameters

Response

Status codes

Initialize registration flow for native apps

Endpoint

Query parameters

Response

Status codes

Get registration flow

Endpoint

Query parameters

Headers

Response

Status codes

Submit registration flow

Endpoint

Query parameters

Headers

Request body

Response (API flows)

Response (browser flows)

Status codes

Error responses