Skip to main content
Version: v0.6

REST API

Welcome to the Ory Kratos HTTP API documentation!

info

You are viewing REST API documentation. This documentation is auto-generated from a swagger specification which itself is generated from annotations in the source code of the project. It is possible that this documentation includes bugs and that code samples are incomplete or wrong.

If you find issues in the respective documentation, please do not edit the Markdown files directly (as they are generated) but raise an issue on the project's GitHub presence instead. This documentation will improve over time with your help! If you have ideas how to improve this part of the documentation, feel free to share them in a GitHub issue any time.

Authentication#

  • API Key (sessionCookie)
    • Parameter Name: Cookie, in: header.
  • API Key (sessionToken)
    • Parameter Name: X-Session-Token, in: header.

health#

Check alive status#

GET /health/alive HTTP/1.1
Accept: application/json

This endpoint returns a 200 status code when the HTTP server is up running. This status does currently not include checks whether the database connection is working.

If the service supports TLS Edge Termination, this endpoint does not require the X-Forwarded-Proto header to be set.

Be aware that if you are running multiple nodes of this service, the health status will never refer to the cluster state, only to a single instance.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKhealthStatushealthStatus
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"status": "string"
}

Code samples#

curl -X GET /health/alive \
-H 'Accept: application/json'

Check readiness status#

GET /health/ready HTTP/1.1
Accept: application/json

This endpoint returns a 200 status code when the HTTP server is up running and the environment dependencies (e.g. the database) are responsive as well.

If the service supports TLS Edge Termination, this endpoint does not require the X-Forwarded-Proto header to be set.

Be aware that if you are running multiple nodes of this service, the health status will never refer to the cluster state, only to a single instance.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKhealthStatushealthStatus
503Service UnavailablehealthNotReadyStatushealthNotReadyStatus
Examples#
200 response#
{
"status": "string"
}

Code samples#

curl -X GET /health/ready \
-H 'Accept: application/json'

Administrative Endpoints#

List Identities#

GET /identities HTTP/1.1
Accept: application/json

Lists all identities. Does not support search at the moment.

Learn how identities work in Ory Kratos' User And Identity Model Documentation.

Parameters#

ParameterInTypeRequiredDescription
per_pagequeryinteger(int64)falseItems per Page
pagequeryinteger(int64)falsePagination Page
Detailed descriptions#

per_page: Items per Page

This is the number of items per page.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKA list of identities.Inline
500Internal Server ErrorgenericErrorgenericError
Response Schema#

Status Code 200

NameTypeRequiredRestrictionsDescription
anonymous[Identity]falsenonenone
» idUUID(uuid4)truenonenone
» recovery_addresses[RecoveryAddress]falsenoneRecoveryAddresses contains all the addresses that can be used to recover an identity.
»» idUUID(uuid4)truenonenone
»» valuestringtruenonenone
»» viaRecoveryAddressTypetruenonenone
» schema_idstringtruenoneSchemaID is the ID of the JSON Schema to be used for validating the identity's traits.
» schema_urlstringtruenoneSchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from.

format: url
» traitsTraitstruenonenone
» verifiable_addresses[VerifiableAddress]falsenoneVerifiableAddresses contains all the addresses that can be verified by the user.
»» idUUID(uuid4)truenonenone
»» statusVerifiableAddressStatustruenonenone
»» valuestringtruenonenone
»» verifiedbooleantruenonenone
»» verified_atNullTime(date-time)falsenonenone
»» viaVerifiableAddressTypetruenonenone
Examples#
200 response#
[
{
"id": "string",
"recovery_addresses": [
{
"id": "string",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": {},
"verifiable_addresses": [
{
"id": "string",
"status": "string",
"value": "string",
"verified": true,
"verified_at": "2019-08-24T14:15:22Z",
"via": "string"
}
]
}
]

Code samples#

curl -X GET /identities \
-H 'Accept: application/json'

Create an Identity#

POST /identities HTTP/1.1
Content-Type: application/json
Accept: application/json

This endpoint creates an identity. It is NOT possible to set an identity's credentials (password, ...) using this method! A way to achieve that will be introduced in the future.

Learn how identities work in Ory Kratos' User And Identity Model Documentation.

Request body#

{
"schema_id": "string",
"traits": {}
}

Parameters#

ParameterInTypeRequiredDescription
bodybodyCreateIdentityfalsenone

Responses#

Overview#
StatusMeaningDescriptionSchema
201CreatedA single identity.Identity
400Bad RequestgenericErrorgenericError
409ConflictgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
201 response#
{
"id": "string",
"recovery_addresses": [
{
"id": "string",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": {},
"verifiable_addresses": [
{
"id": "string",
"status": "string",
"value": "string",
"verified": true,
"verified_at": "2019-08-24T14:15:22Z",
"via": "string"
}
]
}

Code samples#

curl -X POST /identities \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Get an Identity#

GET /identities/{id} HTTP/1.1
Accept: application/json

Learn how identities work in Ory Kratos' User And Identity Model Documentation.

Parameters#

ParameterInTypeRequiredDescription
idpathstringtrueID must be set to the ID of identity you want to get

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKA single identity.Identity
400Bad RequestgenericErrorgenericError
404Not FoundgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"id": "string",
"recovery_addresses": [
{
"id": "string",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": {},
"verifiable_addresses": [
{
"id": "string",
"status": "string",
"value": "string",
"verified": true,
"verified_at": "2019-08-24T14:15:22Z",
"via": "string"
}
]
}

Code samples#

curl -X GET /identities/{id} \
-H 'Accept: application/json'

Update an Identity#

PUT /identities/{id} HTTP/1.1
Content-Type: application/json
Accept: application/json

This endpoint updates an identity. It is NOT possible to set an identity's credentials (password, ...) using this method! A way to achieve that will be introduced in the future.

The full identity payload (except credentials) is expected. This endpoint does not support patching.

Learn how identities work in Ory Kratos' User And Identity Model Documentation.

Request body#

{
"schema_id": "string",
"traits": {}
}

Parameters#

ParameterInTypeRequiredDescription
idpathstringtrueID must be set to the ID of identity you want to update
bodybodyUpdateIdentityfalsenone

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKA single identity.Identity
400Bad RequestgenericErrorgenericError
404Not FoundgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"id": "string",
"recovery_addresses": [
{
"id": "string",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": {},
"verifiable_addresses": [
{
"id": "string",
"status": "string",
"value": "string",
"verified": true,
"verified_at": "2019-08-24T14:15:22Z",
"via": "string"
}
]
}

Code samples#

curl -X PUT /identities/{id} \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Delete an Identity#

DELETE /identities/{id} HTTP/1.1
Accept: application/json

Calling this endpoint irrecoverably and permanently deletes the identity given its ID. This action can not be undone. This endpoint returns 204 when the identity was deleted or when the identity was not found, in which case it is assumed that is has been deleted already.

Learn how identities work in Ory Kratos' User And Identity Model Documentation.

Parameters#

ParameterInTypeRequiredDescription
idpathstringtrueID is the identity's ID.

Responses#

Overview#
StatusMeaningDescriptionSchema
204No ContentEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
404Not FoundgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
404 response#
{
"error": {
"code": 404,
"debug": "The database adapter was unable to find the element",
"details": {},
"message": "string",
"reason": "string",
"request": "string",
"status": "string"
}
}

Code samples#

curl -X DELETE /identities/{id} \
-H 'Accept: application/json'

Get snapshot metrics from the Hydra service. If you're using k8s, you can then add annotations to#

your deployment like so:

GET /metrics/prometheus HTTP/1.1
metadata:
annotations:
prometheus.io/port: "4434"
prometheus.io/path: "/metrics/prometheus"

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None

Code samples#

curl -X GET /metrics/prometheus

Create a Recovery Link#

POST /recovery/link HTTP/1.1
Content-Type: application/json
Accept: application/json

This endpoint creates a recovery link which should be given to the user in order for them to recover (or activate) their account.

Request body#

{
"expires_in": "string",
"identity_id": "string"
}

Parameters#

ParameterInTypeRequiredDescription
bodybodyCreateRecoveryLinkfalsenone

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKrecoveryLinkrecoveryLink
400Bad RequestgenericErrorgenericError
404Not FoundgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"expires_at": "2019-08-24T14:15:22Z",
"recovery_link": "string"
}

Code samples#

curl -X POST /recovery/link \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Public Endpoints#

getSchema#

GET /schemas/{id} HTTP/1.1
Accept: application/json

Get a Traits Schema Definition

Parameters#

ParameterInTypeRequiredDescription
idpathstringtrueID must be set to the ID of schema you want to get

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKjsonSchemajsonSchema
404Not FoundgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{}

Code samples#

curl -X GET /schemas/{id} \
-H 'Accept: application/json'

Initialize Browser-Based Logout User Flow#

GET /self-service/browser/flows/logout HTTP/1.1
Accept: application/json

This endpoint initializes a logout flow.

This endpoint is NOT INTENDED for API clients and only works with browsers (Chrome, Firefox, ...).

On successful logout, the browser will be redirected (HTTP 302 Found) to the return_to parameter of the initial request or fall back to urls.default_return_to.

More information can be found at Ory Kratos User Logout Documentation.

Responses#

Overview#
StatusMeaningDescriptionSchema
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
500Internal Server ErrorgenericErrorgenericError
Examples#
500 response#
{
"error": {
"code": 404,
"debug": "The database adapter was unable to find the element",
"details": {},
"message": "string",
"reason": "string",
"request": "string",
"status": "string"
}
}

Code samples#

curl -X GET /self-service/browser/flows/logout \
-H 'Accept: application/json'

Get User-Facing Self-Service Errors#

GET /self-service/errors?error=string HTTP/1.1
Accept: application/json

This endpoint returns the error associated with a user-facing self service errors.

This endpoint supports stub values to help you implement the error UI:

?error=stub:500 - returns a stub 500 (Internal Server Error) error.

More information can be found at Ory Kratos User User Facing Error Documentation.

Parameters#

ParameterInTypeRequiredDescription
errorquerystringtrueError is the container's ID

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKUser-facing error responseerrorContainer
403ForbiddengenericErrorgenericError
404Not FoundgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"errors": {},
"id": "string"
}

Code samples#

curl -X GET /self-service/errors?error=string \
-H 'Accept: application/json'

Submit a Login Flow#

POST /self-service/login?flow=string HTTP/1.1
Content-Type: application/json
Accept: application/json

Use this endpoint to complete a login flow. This endpoint behaves differently for API and browser flows.

API flows expect application/json to be sent in the body and responds with HTTP 200 and a application/json body with the session token on success; HTTP 302 redirect to a fresh login flow if the original flow expired with the appropriate error messages set; HTTP 400 on form validation errors.

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

More information can be found at Ory Kratos User Login and User Registration Documentation.

Request body#

{}
{}

Parameters#

ParameterInTypeRequiredDescription
flowquerystringtrueThe Login Flow ID
bodybodysubmitSelfServiceLoginFlowfalsenone
Detailed descriptions#

flow: The Login Flow ID

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

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKloginViaApiResponseloginViaApiResponse
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
400Bad RequestloginFlowloginFlow
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"session": {
"active": true,
"authenticated_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z",
"id": "string",
"identity": {
"id": "string",
"recovery_addresses": [
{
"id": "string",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": {},
"verifiable_addresses": [
{
"id": "string",
"status": "string",
"value": "string",
"verified": true,
"verified_at": "2019-08-24T14:15:22Z",
"via": "string"
}
]
},
"issued_at": "2019-08-24T14:15:22Z"
},
"session_token": "string"
}

Code samples#

curl -X POST /self-service/login?flow=string \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Initialize Login Flow for API clients#

GET /self-service/login/api HTTP/1.1
Accept: application/json

This endpoint initiates a login flow for API clients such as mobile devices, smart TVs, and so on.

If a valid provided session cookie or session token is provided, a 400 Bad Request error will be returned unless the URL query parameter ?refresh=true is set.

To fetch an existing login flow call /self-service/login/flows?flow=<flow_id>.

warning

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, including CSRF login attacks.

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

More information can be found at Ory Kratos User Login and User Registration Documentation.

Parameters#

ParameterInTypeRequiredDescription
refreshquerybooleanfalseRefresh a login session
Detailed descriptions#

refresh: Refresh a login session

If set to true, this will refresh an existing login session by asking the user to sign in again. This will reset the authenticated_at time of the session.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKloginFlowloginFlow
400Bad RequestgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"active": "string",
"expires_at": "2019-08-24T14:15:22Z",
"forced": true,
"id": "string",
"issued_at": "2019-08-24T14:15:22Z",
"request_url": "string",
"type": "string",
"ui": {
"action": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"method": "string",
"nodes": [
{
"attributes": {},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
}
}

Code samples#

curl -X GET /self-service/login/api \
-H 'Accept: application/json'

Initialize Login Flow for browsers#

GET /self-service/login/browser HTTP/1.1
Accept: application/json

This endpoint initializes a browser-based user login flow. Once initialized, the browser will be redirected to selfservice.flows.login.ui_url with the flow ID set as the query parameter ?flow=. If a valid user session exists already, the browser will be redirected to urls.default_redirect_url unless the query parameter ?refresh=true was set.

This endpoint is NOT INTENDED for API clients and only works with browsers (Chrome, Firefox, ...).

More information can be found at Ory Kratos User Login and User Registration Documentation.

Responses#

Overview#
StatusMeaningDescriptionSchema
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
500Internal Server ErrorgenericErrorgenericError
Examples#
500 response#
{
"error": {
"code": 404,
"debug": "The database adapter was unable to find the element",
"details": {},
"message": "string",
"reason": "string",
"request": "string",
"status": "string"
}
}

Code samples#

curl -X GET /self-service/login/browser \
-H 'Accept: application/json'

Get Login Flow#

GET /self-service/login/flows?id=string HTTP/1.1
Accept: application/json

This endpoint returns a login flow's context with, for example, error details and other information.

More information can be found at Ory Kratos User Login and User Registration Documentation.

Parameters#

ParameterInTypeRequiredDescription
idquerystringtrueThe Login Flow ID
Detailed descriptions#

id: The Login Flow ID

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

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKloginFlowloginFlow
403ForbiddengenericErrorgenericError
404Not FoundgenericErrorgenericError
410GonegenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"active": "string",
"expires_at": "2019-08-24T14:15:22Z",
"forced": true,
"id": "string",
"issued_at": "2019-08-24T14:15:22Z",
"request_url": "string",
"type": "string",
"ui": {
"action": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"method": "string",
"nodes": [
{
"attributes": {},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
}
}

Code samples#

curl -X GET /self-service/login/flows?id=string \
-H 'Accept: application/json'

Complete Recovery Flow#

POST /self-service/recovery?flow=string HTTP/1.1
Content-Type: application/json
Accept: application/json

Use this endpoint to complete a recovery flow. This endpoint behaves differently for API and browser flows and has several states:

choose_method expects flow (in the URL query) and email (in the body) to be sent and works with API- and Browser-initiated flows. For API clients it either returns a HTTP 200 OK when the form is valid and HTTP 400 OK when the form is invalid and a HTTP 302 Found redirect with a fresh recovery flow if the flow was otherwise invalid (e.g. expired). For Browser clients it returns a HTTP 302 Found redirect to the Recovery UI URL with the Recovery Flow ID appended. sent_email is the success state after choose_method for the link method and allows the user to request another recovery email. It works for both API and Browser-initiated flows and returns the same responses as the flow in choose_method state. passed_challenge expects a token to be sent in the URL query and given the nature of the flow ("sending a recovery link") does not have any API capabilities. The server responds with a HTTP 302 Found redirect either to the Settings UI URL (if the link was valid) and instructs the user to update their password, or a redirect to the Recover UI URL with a new Recovery Flow ID which contains an error message that the recovery link was invalid.

More information can be found at Ory Kratos Account Recovery Documentation.

Request body#

{}
{}

Parameters#

ParameterInTypeRequiredDescription
flowquerystringtrueThe Registration Flow ID
bodybodysubmitSelfServiceRecoveryFlowfalsenone
Detailed descriptions#

flow: The Registration Flow ID

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

Responses#

Overview#
StatusMeaningDescriptionSchema
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
400Bad RequestrecoveryFlowrecoveryFlow
500Internal Server ErrorgenericErrorgenericError
Examples#
400 response#
{
"active": "string",
"expires_at": "2019-08-24T14:15:22Z",
"id": "string",
"issued_at": "2019-08-24T14:15:22Z",
"request_url": "string",
"state": "string",
"type": "string",
"ui": {
"action": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"method": "string",
"nodes": [
{
"attributes": {},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
}
}

Code samples#

curl -X POST /self-service/recovery?flow=string \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Initialize Recovery Flow for API Clients#

GET /self-service/recovery/api HTTP/1.1
Accept: application/json

This endpoint initiates a recovery flow for API clients such as mobile devices, smart TVs, and so on.

If a valid provided session cookie or session token is provided, a 400 Bad Request error.

To fetch an existing recovery flow call /self-service/recovery/flows?flow=<flow_id>.

warning

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.

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

More information can be found at Ory Kratos Account Recovery Documentation.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKrecoveryFlowrecoveryFlow
400Bad RequestgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"active": "string",
"expires_at": "2019-08-24T14:15:22Z",
"id": "string",
"issued_at": "2019-08-24T14:15:22Z",
"request_url": "string",
"state": "string",
"type": "string",
"ui": {
"action": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"method": "string",
"nodes": [
{
"attributes": {},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
}
}

Code samples#

curl -X GET /self-service/recovery/api \
-H 'Accept: application/json'

Initialize Recovery Flow for Browser Clients#

GET /self-service/recovery/browser HTTP/1.1
Accept: application/json

This endpoint initializes a browser-based account recovery flow. Once initialized, the browser will be redirected to selfservice.flows.recovery.ui_url with the flow ID set as the query parameter ?flow=. If a valid user session exists, the browser is returned to the configured return URL.

This endpoint is NOT INTENDED for API clients and only works with browsers (Chrome, Firefox, ...).

More information can be found at Ory Kratos Account Recovery Documentation.

Responses#

Overview#
StatusMeaningDescriptionSchema
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
500Internal Server ErrorgenericErrorgenericError
Examples#
500 response#
{
"error": {
"code": 404,
"debug": "The database adapter was unable to find the element",
"details": {},
"message": "string",
"reason": "string",
"request": "string",
"status": "string"
}
}

Code samples#

curl -X GET /self-service/recovery/browser \
-H 'Accept: application/json'

Get information about a recovery flow#

GET /self-service/recovery/flows?id=string HTTP/1.1
Accept: application/json

This endpoint returns a recovery flow's context with, for example, error details and other information.

More information can be found at Ory Kratos Account Recovery Documentation.

Parameters#

ParameterInTypeRequiredDescription
idquerystringtrueThe Flow ID
Detailed descriptions#

id: The Flow ID

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

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKrecoveryFlowrecoveryFlow
404Not FoundgenericErrorgenericError
410GonegenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"active": "string",
"expires_at": "2019-08-24T14:15:22Z",
"id": "string",
"issued_at": "2019-08-24T14:15:22Z",
"request_url": "string",
"state": "string",
"type": "string",
"ui": {
"action": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"method": "string",
"nodes": [
{
"attributes": {},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
}
}

Code samples#

curl -X GET /self-service/recovery/flows?id=string \
-H 'Accept: application/json'

Complete Recovery Flow with Link Method#

POST /self-service/recovery/methods/link HTTP/1.1
Content-Type: application/json
Accept: application/json

Use this endpoint to complete a recovery flow using the link method. This endpoint behaves differently for API and browser flows and has several states:

choose_method expects flow (in the URL query) and email (in the body) to be sent and works with API- and Browser-initiated flows. For API clients it either returns a HTTP 200 OK when the form is valid and HTTP 400 OK when the form is invalid and a HTTP 302 Found redirect with a fresh recovery flow if the flow was otherwise invalid (e.g. expired). For Browser clients it returns a HTTP 302 Found redirect to the Recovery UI URL with the Recovery Flow ID appended. sent_email is the success state after choose_method and allows the user to request another recovery email. It works for both API and Browser-initiated flows and returns the same responses as the flow in choose_method state. passed_challenge expects a token to be sent in the URL query and given the nature of the flow ("sending a recovery link") does not have any API capabilities. The server responds with a HTTP 302 Found redirect either to the Settings UI URL (if the link was valid) and instructs the user to update their password, or a redirect to the Recover UI URL with a new Recovery Flow ID which contains an error message that the recovery link was invalid.

More information can be found at Ory Kratos Account Recovery Documentation.

Request body#

{
"csrf_token": "string",
"email": "string"
}
csrf_token: string
email: string

Parameters#

ParameterInTypeRequiredDescription
tokenquerystringfalseRecovery Token
flowquerystringfalseThe Flow ID
bodybodysubmitSelfServiceRecoveryFlowWithLinkMethodfalsenone
Detailed descriptions#

token: Recovery Token

The recovery token which completes the recovery request. If the token is invalid (e.g. expired) an error will be shown to the end-user.

flow: The Flow ID

format: uuid

Responses#

Overview#
StatusMeaningDescriptionSchema
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
400Bad RequestrecoveryFlowrecoveryFlow
500Internal Server ErrorgenericErrorgenericError
Examples#
400 response#
{
"active": "string",
"expires_at": "2019-08-24T14:15:22Z",
"id": "string",
"issued_at": "2019-08-24T14:15:22Z",
"request_url": "string",
"state": "string",
"type": "string",
"ui": {
"action": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"method": "string",
"nodes": [
{
"attributes": {},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
}
}

Code samples#

curl -X POST /self-service/recovery/methods/link \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Submit a Registration Flow#

POST /self-service/registration?flow=string HTTP/1.1
Content-Type: application/json
Accept: application/json

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 302 redirect to a fresh registration flow if the original flow expired with the appropriate error messages set; HTTP 400 on form validation errors.

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

More information can be found at Ory Kratos User Login and User Registration Documentation.

Request body#

{}
{}

Parameters#

ParameterInTypeRequiredDescription
flowquerystringtrueThe Registration Flow ID
bodybodysubmitSelfServiceRegistrationFlowfalsenone
Detailed descriptions#

flow: The Registration Flow ID

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

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKregistrationViaApiResponseregistrationViaApiResponse
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
400Bad RequestregistrationFlowregistrationFlow
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"identity": {
"id": "string",
"recovery_addresses": [
{
"id": "string",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": {},
"verifiable_addresses": [
{
"id": "string",
"status": "string",
"value": "string",
"verified": true,
"verified_at": "2019-08-24T14:15:22Z",
"via": "string"
}
]
},
"session": {
"active": true,
"authenticated_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z",
"id": "string",
"identity": {
"id": "string",
"recovery_addresses": [
{
"id": "string",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": {},
"verifiable_addresses": [
{
"id": "string",
"status": "string",
"value": "string",
"verified": true,
"verified_at": "2019-08-24T14:15:22Z",
"via": "string"
}
]
},
"issued_at": "2019-08-24T14:15:22Z"
},
"session_token": "string"
}

Code samples#

curl -X POST /self-service/registration?flow=string \
-H 'Content-Type: application/json' \ -H 'Accept: application/json'

Initialize Registration Flow for API clients#

GET /self-service/registration/api HTTP/1.1
Accept: application/json

This endpoint initiates a registration flow for API clients such as mobile devices, smart TVs, and so on.

If a valid provided session cookie or session token is provided, a 400 Bad Request error will be returned unless the URL query parameter ?refresh=true is set.

To fetch an existing registration flow call /self-service/registration/flows?flow=<flow_id>.

warning

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.

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

More information can be found at Ory Kratos User Login and User Registration Documentation.

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKregistrationFlowregistrationFlow
400Bad RequestgenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"active": "string",
"expires_at": "2019-08-24T14:15:22Z",
"id": "string",
"issued_at": "2019-08-24T14:15:22Z",
"request_url": "string",
"type": "string",
"ui": {
"action": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"method": "string",
"nodes": [
{
"attributes": {},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
}
}

Code samples#

curl -X GET /self-service/registration/api \
-H 'Accept: application/json'

Initialize Registration Flow for browsers#

GET /self-service/registration/browser HTTP/1.1
Accept: application/json

This endpoint initializes a browser-based user registration flow. Once initialized, the browser will be redirected to selfservice.flows.registration.ui_url with the flow ID set as the query parameter ?flow=. If a valid user session exists already, the browser will be redirected to urls.default_redirect_url unless the query parameter ?refresh=true was set.

note

This endpoint is NOT INTENDED for API clients and only works with browsers (Chrome, Firefox, ...).

More information can be found at Ory Kratos User Login and User Registration Documentation.

Responses#

Overview#
StatusMeaningDescriptionSchema
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
500Internal Server ErrorgenericErrorgenericError
Examples#
500 response#
{
"error": {
"code": 404,
"debug": "The database adapter was unable to find the element",
"details": {},
"message": "string",
"reason": "string",
"request": "string",
"status": "string"
}
}

Code samples#

curl -X GET /self-service/registration/browser \
-H 'Accept: application/json'

Get Registration Flow#

GET /self-service/registration/flows?id=string HTTP/1.1
Accept: application/json

This endpoint returns a registration flow's context with, for example, error details and other information.

More information can be found at Ory Kratos User Login and User Registration Documentation.

Parameters#

ParameterInTypeRequiredDescription
idquerystringtrueThe Registration Flow ID
Detailed descriptions#

id: The Registration Flow ID

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

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKregistrationFlowregistrationFlow
403ForbiddengenericErrorgenericError
404Not FoundgenericErrorgenericError
410GonegenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"active": "string",
"expires_at": "2019-08-24T14:15:22Z",
"id": "string",
"issued_at": "2019-08-24T14:15:22Z",
"request_url": "string",
"type": "string",
"ui": {
"action": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"method": "string",
"nodes": [
{
"attributes": {},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
}
}

Code samples#

curl -X GET /self-service/registration/flows?id=string \
-H 'Accept: application/json'

Complete Settings Flow#

POST /self-service/settings?flow=string HTTP/1.1
Content-Type: application/json
Accept: application/json

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

API-initiated flows expect application/json to be sent in the body and respond with HTTP 200 and an application/json body with the session token on success; HTTP 302 redirect to a fresh settings flow if the original flow expired with the appropriate error messages set; HTTP 400 on form validation errors. HTTP 401 when the endpoint is called without a valid session token. HTTP 403 when selfservice.flows.settings.privileged_session_max_age was reached. Implies that the user needs to re-authenticate.

Browser flows expect application/x-www-form-urlencoded to be sent in the body and responds with a HTTP 302 redirect to the post/after settings URL or the return_to value if it was set and if the flow succeeded; a HTTP 302 redirect to the Settings UI URL with the flow ID containing the validation errors otherwise. a HTTP 302 redirect to the login endpoint when selfservice.flows.settings.privileged_session_max_age was reached.

More information can be found at Ory Kratos User Settings & Profile Management Documentation.

Request body#

{}
{}

Parameters#

ParameterInTypeRequiredDescription
flowquerystringtrueThe Settings Flow ID
bodybodysubmitSelfServiceSettingsFlowfalsenone
Detailed descriptions#

flow: The Settings Flow ID

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

Responses#

Overview#
StatusMeaningDescriptionSchema
200OKsettingsViaApiResponsesettingsViaApiResponse
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
400Bad RequestsettingsFlowsettingsFlow
401UnauthorizedgenericErrorgenericError
403ForbiddengenericErrorgenericError
500Internal Server ErrorgenericErrorgenericError
Examples#
200 response#
{
"flow": {
"active"