Skip to main content
Version: v0.6

REST API

Documentation for all public and administrative Ory Kratos APIs. Public and administrative APIs are exposed on different ports. Public APIs can face the public internet without any protection while administrative APIs should never be exposed without prior authorization. To protect the administative API port you should use something like Nginx, Ory Oathkeeper, or any other technology capable of authorizing incoming requests.

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

  • HTTP Authentication, scheme: bearer * API Key (sessionCookie)
    • Parameter Name: ory_kratos_session, in: cookie.
  • HTTP Authentication, scheme: bearer

Administrative Endpoints

Check HTTP Server Status

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

This endpoint returns a HTTP 200 status code when Ory Kratos is accepting incoming HTTP requests. 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
200OKOry Kratos is ready to accept connections.Inline
500Internal Server ErrorgenericErrorgenericError
Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
ยป statusstringtruenoneAlways "ok".
Examples
200 response
{
"status": "string"
}

Code samples

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

Check HTTP Server and Database Status

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

This endpoint returns a HTTP 200 status code when Ory Kratos 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 Ory Kratos, the health status will never refer to the cluster state, only to a single instance.

Responses

Overview
StatusMeaningDescriptionSchema
200OKOry Kratos is ready to accept requests.Inline
503Service UnavailableOry Kratos is not yet ready to accept requests.Inline
Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
ยป statusstringtruenoneAlways "ok".

Status Code 503

NameTypeRequiredRestrictionsDescription
ยป errorsobjecttruenoneErrors contains a list of errors that caused the not ready status.
ยปยป additionalPropertiesstringfalsenonenone
Examples
200 response
{
"status": "string"
}

Code samples

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

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 ErrorjsonErrorjsonError
Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
anonymous[identity]falsenone[An identity can be a real human, a service, an IoT device - everything that
can be described as an "actor" in a system.]
ยป Identity represents an Ory Kratos identityidentityfalsenoneAn identity can be a real human, a service, an IoT device - everything that
can be described as an "actor" in a system.
ยปยป created_atstring(date-time)falsenoneCreatedAt is a helper struct field for gobuffalo.pop.
ยปยป idUUID(uuid4)truenonenone
ยปยป recovery_addresses[RecoveryAddress]falsenoneRecoveryAddresses contains all the addresses that can be used to recover an identity.
ยปยปยป created_atstring(date-time)falsenoneCreatedAt is a helper struct field for gobuffalo.pop.
ยปยปยป idUUID(uuid4)truenonenone
ยปยปยป updated_atstring(date-time)falsenoneUpdatedAt is a helper struct field for gobuffalo.pop.
ยปยปยป 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
ยปยป traitsanytruenoneTraits 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)falsenoneUpdatedAt is a helper struct field for gobuffalo.pop.
ยปยป verifiable_addresses[verifiableIdentityAddress]falsenoneVerifiableAddresses contains all the addresses that can be verified by the user.
ยปยปยป created_atstring(date-time)falsenoneWhen this entry was created
ยปยปยป idUUID(uuid4)truenonenone
ยปยปยป statusidentityVerifiableAddressStatustruenoneVerifiableAddressStatus must not exceed 16 characters as that is the limitation in the SQL Schema
ยปยปยป updated_atstring(date-time)falsenoneWhen this entry was last updated
ยปยปยป valuestringtruenoneThe address value

example foo@user.com
ยปยปยป verifiedbooleantruenoneIndicates if the address has already been verified
ยปยปยป verified_atNullTime(date-time)falsenonenone
ยปยปยป viaidentityVerifiableAddressTypetruenoneVerifiableAddressType must not exceed 16 characters as that is the limitation in the SQL Schema
Examples
200 response
[
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"recovery_addresses": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"updated_at": "2019-08-24T14:15:22Z",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": null,
"updated_at": "2019-08-24T14:15:22Z",
"verifiable_addresses": [
{
"created_at": "2014-01-01T23:28:56.782Z",
"id": "string",
"status": "string",
"updated_at": "2014-01-01T23:28:56.782Z",
"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 RequestjsonErrorjsonError
409ConflictjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
Examples
201 response
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"recovery_addresses": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"updated_at": "2019-08-24T14:15:22Z",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": null,
"updated_at": "2019-08-24T14:15:22Z",
"verifiable_addresses": [
{
"created_at": "2014-01-01T23:28:56.782Z",
"id": "string",
"status": "string",
"updated_at": "2014-01-01T23:28:56.782Z",
"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'

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 FoundjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
Examples
404 response
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}

Code samples

curl -X DELETE /identities/{id} \
-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
404Not FoundjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
Examples
200 response
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"recovery_addresses": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"updated_at": "2019-08-24T14:15:22Z",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": null,
"updated_at": "2019-08-24T14:15:22Z",
"verifiable_addresses": [
{
"created_at": "2014-01-01T23:28:56.782Z",
"id": "string",
"status": "string",
"updated_at": "2014-01-01T23:28:56.782Z",
"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
200OKidentityidentity
400Bad RequestjsonErrorjsonError
404Not FoundjsonErrorjsonError
409ConflictjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
Examples
200 response
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"recovery_addresses": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"updated_at": "2019-08-24T14:15:22Z",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": null,
"updated_at": "2019-08-24T14:15:22Z",
"verifiable_addresses": [
{
"created_at": "2014-01-01T23:28:56.782Z",
"id": "string",
"status": "string",
"updated_at": "2014-01-01T23:28:56.782Z",
"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'

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

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 RequestjsonErrorjsonError
404Not FoundjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
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'

Return Running Software Version.

GET /version HTTP/1.1
Accept: application/json

This endpoint returns the version of Ory Kratos.

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 version will never refer to the cluster state, only to a single instance.

Responses

Overview
StatusMeaningDescriptionSchema
200OKReturns the Ory Kratos version.Inline
Response Schema

Status Code 200

NameTypeRequiredRestrictionsDescription
ยป versionstringtruenoneThe version of Ory Kratos.
Examples
200 response
{
"version": "string"
}

Code samples

curl -X GET /version \
-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 FoundjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
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 ErrorjsonErrorjsonError
Examples
500 response
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}

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 responseselfServiceErrorContainer
403ForbiddenjsonErrorjsonError
404Not FoundjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
Examples
200 response
{
"created_at": "2019-08-24T14:15:22Z",
"errors": [{}],
"id": "string",
"updated_at": "2019-08-24T14:15:22Z"
}

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

{
"csrf_token": "string",
"method": "string",
"password": "string",
"password_identifier": "string"
}
csrf_token: string
method: string
password: string
password_identifier: string

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 ErrorjsonErrorjsonError
Examples
200 response
{
"session": {
"active": true,
"authenticated_at": "2019-08-24T14:15:22Z",
"expires_at": "2019-08-24T14:15:22Z",
"id": "string",
"identity": {
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"recovery_addresses": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"updated_at": "2019-08-24T14:15:22Z",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": null,
"updated_at": "2019-08-24T14:15:22Z",
"verifiable_addresses": [
{
"created_at": "2014-01-01T23:28:56.782Z",
"id": "string",
"status": "string",
"updated_at": "2014-01-01T23:28:56.782Z",
"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 Native Apps and 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 RequestjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
Examples
200 response
{
"active": "string",
"created_at": "2019-08-24T14:15:22Z",
"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": {
"disabled": true,
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
},
"name": "string",
"pattern": "string",
"required": true,
"type": "string",
"value": "string"
},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
},
"updated_at": "2019-08-24T14:15:22Z"
}

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.

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
302FoundEmpty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is typically 201.None
500Internal Server ErrorjsonErrorjsonError
Examples
500 response
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}

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
403ForbiddenjsonErrorjsonError
404Not FoundjsonErrorjsonError
410GonejsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
Examples
200 response
{
"active": "string",
"created_at": "2019-08-24T14:15:22Z",
"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": {
"disabled": true,
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
},
"name": "string",
"pattern": "string",
"required": true,
"type": "string",
"value": "string"
},
"group": "string",
"messages": [
{
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
],
"meta": {
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
}
},
"type": "string"
}
]
},
"updated_at": "2019-08-24T14:15:22Z"
}

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 ErrorjsonErrorjsonError
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": {
"disabled": true,
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
},
"name": "string",
"pattern": "string",
"required": true,
"type": "string",
"value": "string"
},
"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 Native Apps and 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 RequestjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
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": {
"disabled": true,
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
},
"name": "string",
"pattern": "string",
"required": true,
"type": "string",
"value": "string"
},
"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 ErrorjsonErrorjsonError
Examples
500 response
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}

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 FoundjsonErrorjsonError
410GonejsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
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": {
"disabled": true,
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
},
"name": "string",
"pattern": "string",
"required": true,
"type": "string",
"value": "string"
},
"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'
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 ErrorjsonErrorjsonError
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": {
"disabled": true,
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
},
"name": "string",
"pattern": "string",
"required": true,
"type": "string",
"value": "string"
},
"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

{
"csrf_token": "string",
"method": "string",
"password": "string",
"traits": {}
}
csrf_token: string
method: string
password: string
traits: {}

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 ErrorjsonErrorjsonError
Examples
200 response
{
"identity": {
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"recovery_addresses": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"updated_at": "2019-08-24T14:15:22Z",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": null,
"updated_at": "2019-08-24T14:15:22Z",
"verifiable_addresses": [
{
"created_at": "2014-01-01T23:28:56.782Z",
"id": "string",
"status": "string",
"updated_at": "2014-01-01T23:28:56.782Z",
"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": {
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"recovery_addresses": [
{
"created_at": "2019-08-24T14:15:22Z",
"id": "string",
"updated_at": "2019-08-24T14:15:22Z",
"value": "string",
"via": "string"
}
],
"schema_id": "string",
"schema_url": "string",
"traits": null,
"updated_at": "2019-08-24T14:15:22Z",
"verifiable_addresses": [
{
"created_at": "2014-01-01T23:28:56.782Z",
"id": "string",
"status": "string",
"updated_at": "2014-01-01T23:28:56.782Z",
"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 Native Apps and 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 RequestjsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
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": {
"disabled": true,
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
},
"name": "string",
"pattern": "string",
"required": true,
"type": "string",
"value": "string"
},
"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 ErrorjsonErrorjsonError
Examples
500 response
{
"error": {
"code": 404,
"debug": "SQL field \"foo\" is not a bool.",
"details": {},
"message": "The resource could not be found",
"reason": "User with ID 1234 does not exist.",
"request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
"status": "Not Found"
}
}

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
403ForbiddenjsonErrorjsonError
404Not FoundjsonErrorjsonError
410GonejsonErrorjsonError
500Internal Server ErrorjsonErrorjsonError
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": {
"disabled": true,
"label": {
"context": {},
"id": 0,
"text": "string",
"type": "string"
},
"name": "string",
"pattern": "string",
"required": true,
"type": "string",
"value": "string"
},
"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'