Ory frontend API
Endpoints used by frontend applications (e.g. Single-Page-App, Native Apps, Server Apps, ...) to manage a user's own profile.
OpenAPI Specification
openapi: 3.0.3
info:
contact:
email: hi@ory.sh
description: 'Documentation for all of Ory Hydra''s APIs.
'
license:
name: Apache 2.0
title: Ory Hydra api frontend API
version: ''
tags:
- description: Endpoints used by frontend applications (e.g. Single-Page-App, Native Apps, Server Apps, ...) to manage a user's own profile.
name: frontend
paths:
/.well-known/ory/webauthn.js:
get:
description: 'This endpoint provides JavaScript which is needed in order to perform WebAuthn login and registration.
If you are building a JavaScript Browser App (e.g. in ReactJS or AngularJS) you will need to load this file:
```html
<script src="https://public-kratos.example.org/.well-known/ory/webauthn.js" type="script" async />
```
More information can be found at [Ory Kratos User Login](https://www.ory.com/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.com/docs/kratos/self-service/flows/user-registration).'
operationId: getWebAuthnJavaScript
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/webAuthnJavaScript'
description: webAuthnJavaScript
summary: Get WebAuthn JavaScript
tags:
- frontend
x-ory-ratelimit-bucket: hydra-public-high
/self-service/errors:
get:
description: '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:
`?id=stub:500` - returns a stub 500 (Internal Server Error) error.
More information can be found at [Ory Kratos User User Facing Error Documentation](https://www.ory.com/docs/kratos/self-service/flows/user-facing-errors).'
operationId: getFlowError
parameters:
- description: Error is the error's ID
in: query
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/flowError'
description: flowError
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Get User-Flow Errors
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-high
/self-service/fed-cm/parameters:
get:
description: This endpoint returns a list of all available FedCM providers. It is only supported on the Ory Network.
operationId: createFedcmFlow
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/createFedcmFlowResponse'
description: createFedcmFlowResponse
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Get FedCM Parameters
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-high
/self-service/fed-cm/token:
post:
description: 'Use this endpoint to submit a token from a FedCM provider through
`navigator.credentials.get` and log the user in. The parameters from
`navigator.credentials.get` must have come from `GET
self-service/fed-cm/parameters`.'
operationId: updateFedcmFlow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFedcmFlowBody'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UpdateFedcmFlowBody'
required: true
x-originalParamName: Body
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/successfulNativeLogin'
description: successfulNativeLogin
'303':
$ref: '#/components/responses/emptyResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/loginFlow'
description: loginFlow
'410':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/errorBrowserLocationChangeRequired'
description: errorBrowserLocationChangeRequired
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Submit a FedCM token
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-low
/self-service/login:
post:
description: '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 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 login URL or the `return_to` value if it was set and if the login succeeded;
a HTTP 303 redirect to the login 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.
More information can be found at [Ory Kratos User Login](https://www.ory.com/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.com/docs/kratos/self-service/flows/user-registration).'
operationId: updateLoginFlow
parameters:
- description: 'The Login Flow ID
The value for this parameter comes from `flow` URL Query parameter sent to your
application (e.g. `/login?flow=abcde`).'
in: query
name: flow
required: true
schema:
type: string
- description: The Session Token of the Identity performing the settings flow.
in: header
name: X-Session-Token
schema:
type: string
- description: '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.'
in: header
name: Cookie
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updateLoginFlowBody'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/updateLoginFlowBody'
required: true
x-originalParamName: Body
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/successfulNativeLogin'
description: successfulNativeLogin
'303':
$ref: '#/components/responses/emptyResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/loginFlow'
description: loginFlow
'410':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/errorBrowserLocationChangeRequired'
description: errorBrowserLocationChangeRequired
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Submit a Login Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-low
/self-service/login/api:
get:
description: 'This endpoint initiates a login flow for native apps that do not use a browser, 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>`.
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.
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.
`session_aal1_required`: Multi-factor auth (e.g. 2fa) was requested but the user has no session yet.
`security_csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
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](https://www.ory.com/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.com/docs/kratos/self-service/flows/user-registration).'
operationId: createNativeLoginFlow
parameters:
- description: '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.'
in: query
name: refresh
schema:
type: boolean
- description: 'Request a Specific AuthenticationMethod Assurance Level
Use this parameter to upgrade an existing session''s authenticator assurance level (AAL). This
allows you to ask for multi-factor authentication. When an identity sign in using e.g. username+password,
the AAL is 1. If you wish to "upgrade" the session''s security by asking the user to perform TOTP / WebAuth/ ...
you would set this to "aal2".'
in: query
name: aal
schema:
type: string
- description: The Session Token of the Identity performing the settings flow.
in: header
name: X-Session-Token
schema:
type: string
- description: 'EnableSessionTokenExchangeCode requests the login flow to include a code that can be used to retrieve the session token
after the login flow has been completed.'
in: query
name: return_session_token_exchange_code
schema:
type: boolean
- description: The URL to return the browser to after the flow was completed.
in: query
name: return_to
schema:
type: string
- description: 'An optional organization ID that should be used for logging this user in.
This parameter is only effective in the Ory Network.'
in: query
name: organization
schema:
type: string
- description: 'Via should contain the identity''s credential the code should be sent to. Only relevant in aal2 flows.
DEPRECATED: This field is deprecated. Please remove it from your requests. The user will now see a choice
of MFA credentials to choose from to perform the second factor instead.'
in: query
name: via
schema:
type: string
- description: An optional identity schema to use for the login flow.
in: query
name: identity_schema
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/loginFlow'
description: loginFlow
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Login Flow for Native Apps
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
/self-service/login/browser:
get:
description: 'This endpoint initializes a browser-based user login flow. This endpoint will set the appropriate
cookies and anti-CSRF measures required for browser-based flows.
If this endpoint is opened as a link in the browser, it 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.
If this endpoint is called via an AJAX request, 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.
`session_aal1_required`: Multi-factor auth (e.g. 2fa) was requested but the user has no session yet.
`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!
The optional query parameter login_challenge is set when using Kratos with
Hydra in an OAuth2 flow. See the oauth2_provider.url configuration
option.
This endpoint is NOT INTENDED for clients that do not have a browser (Chrome, Firefox, ...) as cookies are needed.
More information can be found at [Ory Kratos User Login](https://www.ory.com/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.com/docs/kratos/self-service/flows/user-registration).'
operationId: createBrowserLoginFlow
parameters:
- description: '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.'
in: query
name: refresh
schema:
type: boolean
- description: 'Request a Specific AuthenticationMethod Assurance Level
Use this parameter to upgrade an existing session''s authenticator assurance level (AAL). This
allows you to ask for multi-factor authentication. When an identity sign in using e.g. username+password,
the AAL is 1. If you wish to "upgrade" the session''s security by asking the user to perform TOTP / WebAuth/ ...
you would set this to "aal2".'
in: query
name: aal
schema:
type: string
- description: The URL to return the browser to after the flow was completed.
in: query
name: return_to
schema:
type: string
- description: '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.'
in: header
name: Cookie
schema:
type: string
- description: 'An optional Hydra login challenge. If present, Kratos will cooperate with
Ory Hydra to act as an OAuth2 identity provider.
The value for this parameter comes from `login_challenge` URL Query parameter sent to your
application (e.g. `/login?login_challenge=abcde`).'
in: query
name: login_challenge
schema:
type: string
- description: 'An optional organization ID that should be used for logging this user in.
This parameter is only effective in the Ory Network.'
in: query
name: organization
schema:
type: string
- description: 'Via should contain the identity''s credential the code should be sent to. Only relevant in aal2 flows.
DEPRECATED: This field is deprecated. Please remove it from your requests. The user will now see a choice
of MFA credentials to choose from to perform the second factor instead.'
in: query
name: via
schema:
type: string
- description: An optional identity schema to use for the login flow.
in: query
name: identity_schema
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/loginFlow'
description: loginFlow
'303':
$ref: '#/components/responses/emptyResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Login Flow for Browsers
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
/self-service/login/flows:
get:
description: 'This endpoint returns a login flow''s context with, for example, error details and other information.
Browser flows expect the anti-CSRF cookie to be included in the request''s HTTP Cookie Header.
For AJAX requests you must ensure that cookies are included in the request or requests will fail.
If you use the browser-flow for server-side apps, the services need to run on a common top-level-domain
and you need to forward the incoming HTTP Cookie header to this endpoint:
```js
pseudo-code example
router.get(''/login'', async function (req, res) {
const flow = await client.getLoginFlow(req.header(''cookie''), req.query[''flow''])
res.render(''login'', flow)
})
```
This request may fail due to several reasons. The `error.id` can be one of:
`session_already_available`: The user is already signed in.
`self_service_flow_expired`: The flow is expired and you should request a new one.
More information can be found at [Ory Kratos User Login](https://www.ory.com/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.com/docs/kratos/self-service/flows/user-registration).'
operationId: getLoginFlow
parameters:
- description: 'The Login Flow ID
The value for this parameter comes from `flow` URL Query parameter sent to your
application (e.g. `/login?flow=abcde`).'
in: query
name: id
required: true
schema:
type: string
- description: '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.'
in: header
name: Cookie
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/loginFlow'
description: loginFlow
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
'410':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Get Login Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-high
/self-service/logout:
get:
description: 'This endpoint logs out an identity in a self-service manner.
If the `Accept` HTTP header is not set to `application/json`, the browser will be redirected (HTTP 303 See Other)
to the `return_to` parameter of the initial request or fall back to `urls.default_return_to`.
If the `Accept` HTTP header is set to `application/json`, a 204 No Content response
will be sent on successful logout instead.
This endpoint is NOT INTENDED for API clients and only works
with browsers (Chrome, Firefox, ...). For API clients you can
call the `/self-service/logout/api` URL directly with the Ory Session Token.
More information can be found at [Ory Kratos User Logout Documentation](https://www.ory.com/docs/next/kratos/self-service/flows/user-logout).'
operationId: updateLogoutFlow
parameters:
- description: 'A Valid Logout Token
If you do not have a logout token because you only have a session cookie,
call `/self-service/logout/browser` to generate a URL for this endpoint.'
in: query
name: token
schema:
type: string
- description: The URL to return to after the logout was completed.
in: query
name: return_to
schema:
type: string
- description: '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.'
in: header
name: Cookie
schema:
type: string
responses:
'204':
$ref: '#/components/responses/emptyResponse'
'303':
$ref: '#/components/responses/emptyResponse'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Update Logout Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-high
/self-service/logout/api:
delete:
description: 'Use this endpoint to log out an identity using an Ory Session Token. If the Ory Session Token was successfully
revoked, the server returns a 204 No Content response. A 204 No Content response is also sent when
the Ory Session Token has been revoked already before.
If the Ory Session Token is malformed or does not exist a 403 Forbidden response will be returned.
This endpoint does not remove any HTTP
Cookies - use the Browser-Based Self-Service Logout Flow instead.'
operationId: performNativeLogout
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/performNativeLogoutBody'
required: true
x-originalParamName: Body
responses:
'204':
$ref: '#/components/responses/emptyResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Perform Logout for Native Apps
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
/self-service/logout/browser:
get:
description: 'This endpoint initializes a browser-based user logout flow and a URL which can be used to log out the user.
This endpoint is NOT INTENDED for API clients and only works
with browsers (Chrome, Firefox, ...). For API clients you can
call the `/self-service/logout/api` URL directly with the Ory Session Token.
The URL is only valid for the currently signed in user. If no user is signed in, this endpoint returns
a 401 error.
When calling this endpoint from a backend, please ensure to properly forward the HTTP cookies.'
operationId: createBrowserLogoutFlow
parameters:
- description: 'HTTP Cookies
If you call this endpoint from a backend, please include the
original Cookie header in the request.'
in: header
name: cookie
schema:
type: string
- description: 'Return to URL
The URL to which the browser should be redirected to after the logout
has been performed.'
in: query
name: return_to
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/logoutFlow'
description: logoutFlow
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create a Logout URL for Browsers
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
/self-service/recovery:
post:
description: 'Use this endpoint to update 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 and Browser clients with HTTP Header `Accept: application/json` it either returns a HTTP 200 OK when the form is valid and HTTP 400 OK when the form is invalid.
and a HTTP 303 See Other redirect with a fresh recovery flow if the flow was otherwise invalid (e.g. expired).
For Browser clients without HTTP Header `Accept` or with `Accept: text/*` it returns a HTTP 303 See Other 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 303 See Other 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](../self-service/flows/account-recovery).'
operationId: updateRecoveryFlow
parameters:
- description: 'The Recovery Flow ID
The value for this parameter comes from `flow` URL Query parameter sent to your
application (e.g. `/recovery?flow=abcde`).'
in: query
name: flow
required: true
schema:
type: string
- description: '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.
This parameter is usually set in a link and not used by any direct API call.'
in: query
name: token
schema:
type: string
- description: '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.'
in: header
name: Cookie
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updateRecoveryFlowBody'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/updateRecoveryFlowBody'
required: true
x-originalParamName: Body
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/recoveryFlow'
description: recoveryFlow
'303':
$ref: '#/components/responses/emptyResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/recoveryFlow'
description: recoveryFlow
'410':
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/errorBrowserLocationChangeRequired'
description: errorBrowserLocationChangeRequired
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Update Recovery Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-low
/self-service/recovery/api:
get:
desc
# --- truncated at 32 KB (213 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ory/refs/heads/main/openapi/ory-frontend-api-openapi.yml