openapi: 3.0.3
info:
contact:
email: office@ory.sh
description: |
This is the API specification for Ory Identities with features such as registration, login, recovery, account verification, profile settings, password reset, identity management, session management, email and sms delivery, and more.
license:
name: Apache 2.0
title: Ory Identities API
version: v26.2.0
servers:
- url: /
tags:
- description: APIs for managing identities.
name: identity
- description: "Endpoints used by frontend applications (e.g. Single-Page-App, Native\
\ Apps, Server Apps, ...) to manage a user's own profile."
name: frontend
- description: APIs for managing email and SMS message delivery.
name: courier
- description: Server Metadata provides relevant information about the running server.
Only available when self-hosting this service.
name: metadata
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
```
More information can be found at [Ory Kratos User Login](https://www.ory.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/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-low
x-accepts:
- application/json
/admin/courier/messages:
get:
description: Lists all messages by given status and recipient.
operationId: listCourierMessages
parameters:
- description: |-
Items per Page
This is the number of items per page to return.
For details on pagination please head over to the [pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_size
required: false
schema:
default: 250
format: int64
maximum: 1000
minimum: 1
type: integer
style: form
- description: |-
Next Page Token
The next page token.
For details on pagination please head over to the [pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_token
required: false
schema:
type: string
style: form
- description: |-
Status filters out messages based on status.
If no value is provided, it doesn't take effect on filter.
explode: true
in: query
name: status
required: false
schema:
$ref: '#/components/schemas/courierMessageStatus'
style: form
- description: |-
Recipient filters out messages based on recipient.
If no value is provided, it doesn't take effect on filter.
explode: true
in: query
name: recipient
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/message'
type: array
description: Paginated Courier Message List Response
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: List Messages
tags:
- courier
x-ory-ratelimit-bucket: kratos-admin-high
x-accepts:
- application/json
/admin/courier/messages/{id}:
get:
description: Gets a specific messages by the given ID.
operationId: getCourierMessage
parameters:
- description: MessageID is the ID of the message.
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/message'
description: message
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Get a Message
tags:
- courier
x-ory-ratelimit-bucket: kratos-admin-medium
x-accepts:
- application/json
/admin/identities:
get:
description: "Lists all [identities](https://www.ory.sh/docs/kratos/concepts/identity-user-model)\
\ in the system. Note: filters cannot be combined."
operationId: listIdentities
parameters:
- description: |-
Deprecated Items per Page
DEPRECATED: Please use `page_token` instead. This parameter will be removed in the future.
This is the number of items per page.
explode: true
in: query
name: per_page
required: false
schema:
default: 250
format: int64
maximum: 1000
minimum: 1
type: integer
style: form
- description: |-
Deprecated Pagination Page
DEPRECATED: Please use `page_token` instead. This parameter will be removed in the future.
This value is currently an integer, but it is not sequential. The value is not the page number, but a
reference. The next page can be any number and some numbers might return an empty list.
For example, page 2 might not follow after page 1. And even if page 3 and 5 exist, but page 4 might not exist.
The first page can be retrieved by omitting this parameter. Following page pointers will be returned in the
`Link` header.
explode: true
in: query
name: page
required: false
schema:
format: int64
type: integer
style: form
- description: |-
Page Size
This is the number of items per page to return. For details on pagination please head over to the
[pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_size
required: false
schema:
default: 250
format: int64
maximum: 500
minimum: 1
type: integer
style: form
- description: |-
Next Page Token
The next page token. For details on pagination please head over to the
[pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_token
required: false
schema:
type: string
style: form
- description: |-
Read Consistency Level (preview)
The read consistency level determines the consistency guarantee for reads:
strong (slow): The read is guaranteed to return the most recent data committed at the start of the read.
eventual (very fast): The result will return data that is about 4.8 seconds old.
The default consistency guarantee can be changed in the Ory Network Console or using the Ory CLI with
`ory patch project --replace '/previews/default_read_consistency_level="strong"'`.
Setting the default consistency level to `eventual` may cause regressions in the future as we add consistency
controls to more APIs. Currently, the following APIs will be affected by this setting:
`GET /admin/identities`
This feature is in preview and only available in Ory Network.
ConsistencyLevelUnset ConsistencyLevelUnset is the unset / default consistency level.
strong ConsistencyLevelStrong ConsistencyLevelStrong is the strong consistency level.
eventual ConsistencyLevelEventual ConsistencyLevelEventual is the eventual consistency level using follower read timestamps.
explode: true
in: query
name: consistency
required: false
schema:
enum:
- ""
- strong
- eventual
type: string
style: form
x-go-enum-desc: |2-
ConsistencyLevelUnset ConsistencyLevelUnset is the unset / default consistency level.
strong ConsistencyLevelStrong ConsistencyLevelStrong is the strong consistency level.
eventual ConsistencyLevelEventual ConsistencyLevelEventual is the eventual consistency level using follower read timestamps.
- description: |-
Retrieve multiple identities by their IDs.
This parameter has the following limitations:
Duplicate or non-existent IDs are ignored.
The order of returned IDs may be different from the request.
This filter does not support pagination. You must implement your own pagination as the maximum number of items returned by this endpoint may not exceed a certain threshold (currently 500).
explode: true
in: query
name: ids
required: false
schema:
items:
type: string
type: array
style: form
- description: |-
CredentialsIdentifier is the identifier (username, email) of the credentials to look up using exact match.
Only one of CredentialsIdentifier and CredentialsIdentifierSimilar can be used.
explode: true
in: query
name: credentials_identifier
required: false
schema:
type: string
style: form
- description: |-
This is an EXPERIMENTAL parameter that WILL CHANGE. Do NOT rely on consistent, deterministic behavior.
THIS PARAMETER WILL BE REMOVED IN AN UPCOMING RELEASE WITHOUT ANY MIGRATION PATH.
CredentialsIdentifierSimilar is the (partial) identifier (username, email) of the credentials to look up using similarity search.
Only one of CredentialsIdentifier and CredentialsIdentifierSimilar can be used.
explode: true
in: query
name: preview_credentials_identifier_similar
required: false
schema:
type: string
style: form
- description: |-
Include Credentials in Response
Include any credential, for example `password` or `oidc`, in the response. When set to `oidc`, This will return
the initial OAuth 2.0 Access Token, OAuth 2.0 Refresh Token and the OpenID Connect ID Token if available.
explode: true
in: query
name: include_credential
required: false
schema:
items:
type: string
type: array
style: form
- description: List identities that belong to a specific organization.
explode: true
in: query
name: organization_id
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/identity'
type: array
description: Paginated Identity List Response
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: List Identities
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-medium
x-accepts:
- application/json
patch:
description: |-
Creates multiple [identities](https://www.ory.com/docs/kratos/concepts/identity-user-model).
You can also use this endpoint to [import credentials](https://www.ory.com/docs/kratos/manage-identities/import-user-accounts-identities),
including passwords, social sign-in settings, and multi-factor authentication methods.
If the patch includes hashed passwords you can import up to 1,000 identities per request.
If the patch includes at least one plaintext password you can import up to 200 identities per request.
Avoid importing large batches with plaintext passwords. They can cause timeouts as the passwords need to be hashed before they are stored.
If at least one identity is imported successfully, the response status is 200 OK.
If all imports fail, the response is one of the following 4xx errors:
400 Bad Request: The request payload is invalid or improperly formatted.
409 Conflict: Duplicate identities or conflicting data were detected.
If you get a 504 Gateway Timeout:
Reduce the batch size
Avoid duplicate identities
Pre-hash passwords with BCrypt
If the issue persists, contact support.
operationId: batchPatchIdentities
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/patchIdentitiesBody'
x-originalParamName: Body
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/batchPatchIdentitiesResponse'
description: batchPatchIdentitiesResponse
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"409":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Create multiple identities
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-content-type: application/json
x-accepts:
- application/json
post:
description: |-
Create an [identity](https://www.ory.sh/docs/kratos/concepts/identity-user-model). This endpoint can also be used to
[import credentials](https://www.ory.sh/docs/kratos/manage-identities/import-user-accounts-identities)
for instance passwords, social sign in configurations or multifactor methods.
operationId: createIdentity
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createIdentityBody'
x-originalParamName: Body
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/identity'
description: identity
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"409":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Create an Identity
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-content-type: application/json
x-accepts:
- application/json
/admin/identities/by/external/{externalID}:
get:
description: |-
Return an [identity](https://www.ory.sh/docs/kratos/concepts/identity-user-model) by its external ID. You can optionally
include credentials (e.g. social sign in connections) in the response by using the `include_credential` query parameter.
operationId: getIdentityByExternalID
parameters:
- description: ExternalID must be set to the ID of identity you want to get
explode: false
in: path
name: externalID
required: true
schema:
type: string
style: simple
- description: |-
Include Credentials in Response
Include any credential, for example `password` or `oidc`, in the response. When set to `oidc`, This will return
the initial OAuth 2.0 Access Token, OAuth 2.0 Refresh Token and the OpenID Connect ID Token if available.
explode: true
in: query
name: include_credential
required: false
schema:
items:
enum:
- password
- oidc
- totp
- lookup_secret
- webauthn
- code
- passkey
- profile
- saml
- link_recovery
- code_recovery
type: string
type: array
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/identity'
description: identity
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Get an Identity by its External ID
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-medium
x-accepts:
- application/json
/admin/identities/{id}:
delete:
description: |-
Calling this endpoint irrecoverably and permanently deletes the [identity](https://www.ory.sh/docs/kratos/concepts/identity-user-model) given its ID. This action can not be undone.
This endpoint returns 204 when the identity was deleted or 404 if the identity was not found.
operationId: deleteIdentity
parameters:
- description: ID is the identity's ID.
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
responses:
"204":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Delete an Identity
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-accepts:
- application/json
get:
description: |-
Return an [identity](https://www.ory.sh/docs/kratos/concepts/identity-user-model) by its ID. You can optionally
include credentials (e.g. social sign in connections) in the response by using the `include_credential` query parameter.
operationId: getIdentity
parameters:
- description: ID must be set to the ID of identity you want to get
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
- description: |-
Include Credentials in Response
Include any credential, for example `password` or `oidc`, in the response. When set to `oidc`, This will return
the initial OAuth 2.0 Access Token, OAuth 2.0 Refresh Token and the OpenID Connect ID Token if available.
explode: true
in: query
name: include_credential
required: false
schema:
items:
enum:
- password
- oidc
- totp
- lookup_secret
- webauthn
- code
- passkey
- profile
- saml
- link_recovery
- code_recovery
type: string
type: array
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/identity'
description: identity
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Get an Identity
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-low
x-accepts:
- application/json
patch:
description: |-
Partially updates an [identity's](https://www.ory.sh/docs/kratos/concepts/identity-user-model) field using [JSON Patch](https://jsonpatch.com/).
The fields `id`, `stateChangedAt` and `credentials` can not be updated using this method.
operationId: patchIdentity
parameters:
- description: ID must be set to the ID of identity you want to update
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/jsonPatchDocument'
x-originalParamName: Body
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/identity'
description: identity
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"409":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Patch an Identity
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-content-type: application/json
x-accepts:
- application/json
put:
description: |-
This endpoint updates an [identity](https://www.ory.sh/docs/kratos/concepts/identity-user-model). The full identity
payload, except credentials, is expected. For partial updates, use the [patchIdentity](https://www.ory.sh/docs/reference/api#tag/identity/operation/patchIdentity) operation.
A credential can be provided via the `credentials` field in the request body.
If provided, the credentials will be imported and added to the existing credentials of the identity.
operationId: updateIdentity
parameters:
- description: ID must be set to the ID of identity you want to update
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updateIdentityBody'
x-originalParamName: Body
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/identity'
description: identity
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"409":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Update an Identity
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-content-type: application/json
x-accepts:
- application/json
/admin/identities/{id}/credentials/{type}:
delete:
description: |-
Delete an [identity](https://www.ory.sh/docs/kratos/concepts/identity-user-model) credential by its type.
You cannot delete passkeys or code auth credentials through this API.
operationId: deleteIdentityCredentials
parameters:
- description: ID is the identity's ID.
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
- description: |-
Type is the type of credentials to delete.
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
explode: false
in: path
name: type
required: true
schema:
enum:
- password
- oidc
- totp
- lookup_secret
- webauthn
- code
- passkey
- profile
- saml
- link_recovery
- code_recovery
type: string
style: simple
x-go-enum-desc: |-
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
- description: |-
Identifier is the identifier of the OIDC/SAML credential to delete.
Find the identifier by calling the `GET /admin/identities/{id}?include_credential={oidc,saml}` endpoint.
explode: true
in: query
name: identifier
required: false
schema:
type: string
style: form
responses:
"204":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Delete a credential for a specific identity
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-accepts:
- application/json
/admin/identities/{id}/sessions:
delete:
description: Calling this endpoint irrecoverably and permanently deletes and
invalidates all sessions that belong to the given Identity.
operationId: deleteIdentitySessions
parameters:
- description: ID is the identity's ID.
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
responses:
"204":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Delete & Invalidate an Identity's Sessions
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-accepts:
- application/json
get:
description: This endpoint returns all sessions that belong to the given Identity.
operationId: listIdentitySessions
parameters:
- description: |-
Deprecated Items per Page
DEPRECATED: Please use `page_token` instead. This parameter will be removed in the future.
This is the number of items per page.
explode: true
in: query
name: per_page
required: false
schema:
default: 250
format: int64
maximum: 1000
minimum: 1
type: integer
style: form
- description: |-
Deprecated Pagination Page
DEPRECATED: Please use `page_token` instead. This parameter will be removed in the future.
This value is currently an integer, but it is not sequential. The value is not the page number, but a
reference. The next page can be any number and some numbers might return an empty list.
For example, page 2 might not follow after page 1. And even if page 3 and 5 exist, but page 4 might not exist.
The first page can be retrieved by omitting this parameter. Following page pointers will be returned in the
`Link` header.
explode: true
in: query
name: page
required: false
schema:
format: int64
type: integer
style: form
- description: |-
Page Size
This is the number of items per page to return. For details on pagination please head over to the
[pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_size
required: false
schema:
default: 250
format: int64
maximum: 500
minimum: 1
type: integer
style: form
- description: |-
Next Page Token
The next page token. For details on pagination please head over to the
[pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_token
required: false
schema:
type: string
style: form
- description: ID is the identity's ID.
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
- description: "Active is a boolean flag that filters out sessions based on\
\ the state. If no value is provided, all sessions are returned."
explode: true
in: query
name: active
required: false
schema:
type: boolean
style: form
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/session'
type: array
description: List Identity Sessions Response
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: List an Identity's Sessions
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-medium
x-accepts:
- application/json
/admin/recovery/code:
post:
description: |-
This endpoint creates a recovery code which should be given to the user in order for them to recover
(or activate) their account.
operationId: createRecoveryCodeForIdentity
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createRecoveryCodeForIdentityBody'
x-originalParamName: Body
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/recoveryCodeForIdentity'
description: recoveryCodeForIdentity
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Create a Recovery Code
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-content-type: application/json
x-accepts:
- application/json
/admin/recovery/link:
post:
description: |-
This endpoint creates a recovery link which should be given to the user in order for them to recover
(or activate) their account.
operationId: createRecoveryLinkForIdentity
parameters:
- explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createRecoveryLinkForIdentityBody'
x-originalParamName: Body
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/recoveryLinkForIdentity'
description: recoveryLinkForIdentity
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Create a Recovery Link
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-content-type: application/json
x-accepts:
- application/json
/admin/sessions:
get:
description: Listing all sessions that exist.
operationId: listSessions
parameters:
- description: |-
Items per Page
This is the number of items per page to return.
For details on pagination please head over to the [pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_size
required: false
schema:
default: 250
format: int64
maximum: 1000
minimum: 1
type: integer
style: form
- description: |-
Next Page Token
The next page token.
For details on pagination please head over to the [pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_token
required: false
schema:
type: string
style: form
- description: "Active is a boolean flag that filters out sessions based on\
\ the state. If no value is provided, all sessions are returned."
explode: true
in: query
name: active
required: false
schema:
type: boolean
style: form
- description: |-
ExpandOptions is a query parameter encoded list of all properties that must be expanded in the Session.
If no value is provided, the expandable properties are skipped.
explode: true
in: query
name: expand
required: false
schema:
items:
enum:
- identity
- devices
type: string
type: array
style: form
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/session'
type: array
description: |-
Session List Response
The response given when listing sessions in an administrative context.
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: List All Sessions
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-medium
x-accepts:
- application/json
/admin/sessions/{id}:
delete:
description: Calling this endpoint deactivates the specified session. Session
data is not deleted.
operationId: disableSession
parameters:
- description: ID is the session's ID.
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
responses:
"204":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Deactivate a Session
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-accepts:
- application/json
get:
description: |-
This endpoint is useful for:
Getting a session object with all specified expandables that exist in an administrative context.
operationId: getSession
parameters:
- description: |-
ExpandOptions is a query parameter encoded list of all properties that must be expanded in the Session.
Example - ?expand=Identity&expand=Devices
If no value is provided, the expandable properties are skipped.
explode: true
in: query
name: expand
required: false
schema:
items:
enum:
- identity
- devices
type: string
type: array
style: form
- description: ID is the session's ID.
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/session'
description: session
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Get Session
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-low
x-accepts:
- application/json
/admin/sessions/{id}/extend:
patch:
description: |-
Calling this endpoint extends the given session ID. If `session.earliest_possible_extend` is set it
will only extend the session after the specified time has passed.
This endpoint returns per default a 204 No Content response on success. Older Ory Network projects may
return a 200 OK response with the session in the body. Returning the session as part of the response
will be deprecated in the future and should not be relied upon.
This endpoint ignores consecutive requests to extend the same session and returns a 404 error in those
scenarios. This endpoint also returns 404 errors if the session does not exist.
Retrieve the session ID from the `/sessions/whoami` endpoint / `toSession` SDK method.
operationId: extendSession
parameters:
- description: ID is the session's ID.
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/session'
description: session
"204":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
security:
- oryAccessToken: []
summary: Extend a Session
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-high
x-accepts:
- application/json
/health/alive:
get:
description: |-
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.
operationId: isAlive
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/isAlive_200_response'
description: Ory Kratos is ready to accept connections.
default:
content:
text/plain:
schema:
type: string
description: Unexpected error
summary: Check HTTP Server Status
tags:
- metadata
x-accepts:
- application/json
- text/plain
/health/ready:
get:
description: |-
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.
operationId: isReady
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/isAlive_200_response'
description: Ory Kratos is ready to accept requests.
"503":
content:
application/json:
schema:
$ref: '#/components/schemas/isReady_503_response'
description: Ory Kratos is not yet ready to accept requests.
default:
content:
text/plain:
schema:
type: string
description: Unexpected error
summary: Check HTTP Server and Database Status
tags:
- metadata
x-accepts:
- application/json
- text/plain
/schemas:
get:
description: Returns a list of all identity schemas currently in use.
operationId: listIdentitySchemas
parameters:
- description: |-
Deprecated Items per Page
DEPRECATED: Please use `page_token` instead. This parameter will be removed in the future.
This is the number of items per page.
explode: true
in: query
name: per_page
required: false
schema:
default: 250
format: int64
maximum: 1000
minimum: 1
type: integer
style: form
- description: |-
Deprecated Pagination Page
DEPRECATED: Please use `page_token` instead. This parameter will be removed in the future.
This value is currently an integer, but it is not sequential. The value is not the page number, but a
reference. The next page can be any number and some numbers might return an empty list.
For example, page 2 might not follow after page 1. And even if page 3 and 5 exist, but page 4 might not exist.
The first page can be retrieved by omitting this parameter. Following page pointers will be returned in the
`Link` header.
explode: true
in: query
name: page
required: false
schema:
format: int64
type: integer
style: form
- description: |-
Page Size
This is the number of items per page to return. For details on pagination please head over to the
[pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_size
required: false
schema:
default: 250
format: int64
maximum: 500
minimum: 1
type: integer
style: form
- description: |-
Next Page Token
The next page token. For details on pagination please head over to the
[pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_token
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/identitySchemas'
description: List Identity JSON Schemas Response
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Get all Identity Schemas
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-medium
x-accepts:
- application/json
/schemas/{id}:
get:
description: Return a specific identity schema.
operationId: getIdentitySchema
parameters:
- description: ID must be set to the ID of schema you want to get
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/identitySchema'
description: identitySchema
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Get Identity JSON Schema
tags:
- identity
x-ory-ratelimit-bucket: kratos-admin-medium
x-accepts:
- application/json
/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.sh/docs/kratos/self-service/flows/user-facing-errors).
operationId: getFlowError
parameters:
- description: Error is the error's ID
explode: true
in: query
name: id
required: true
schema:
type: string
style: form
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-low
x-accepts:
- application/json
/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-low
x-accepts:
- application/json
/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":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"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-high
x-content-type: application/json
x-accepts:
- application/json
/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.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/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`).
explode: true
in: query
name: flow
required: true
schema:
type: string
style: form
- description: The Session Token of the Identity performing the settings flow.
explode: false
in: header
name: X-Session-Token
required: false
schema:
type: string
style: simple
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
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":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"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-high
x-content-type: application/json
x-accepts:
- application/json
/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=`.
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.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/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.
explode: true
in: query
name: refresh
required: false
schema:
type: boolean
style: form
- 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".
explode: true
in: query
name: aal
required: false
schema:
type: string
style: form
- description: The Session Token of the Identity performing the settings flow.
explode: false
in: header
name: X-Session-Token
required: false
schema:
type: string
style: simple
- 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.
explode: true
in: query
name: return_session_token_exchange_code
required: false
schema:
type: boolean
style: form
- description: The URL to return the browser to after the flow was completed.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
- description: |-
An optional organization ID that should be used for logging this user in.
This parameter is only effective in the Ory Network.
explode: true
in: query
name: organization
required: false
schema:
type: string
style: form
- 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.
explode: true
in: query
name: via
required: false
schema:
type: string
style: form
- description: An optional identity schema to use for the login flow.
explode: true
in: query
name: identity_schema
required: false
schema:
type: string
style: form
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
x-accepts:
- application/json
/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.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/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.
explode: true
in: query
name: refresh
required: false
schema:
type: boolean
style: form
- 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".
explode: true
in: query
name: aal
required: false
schema:
type: string
style: form
- description: The URL to return the browser to after the flow was completed.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
- 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`).
explode: true
in: query
name: login_challenge
required: false
schema:
type: string
style: form
- description: |-
An optional organization ID that should be used for logging this user in.
This parameter is only effective in the Ory Network.
explode: true
in: query
name: organization
required: false
schema:
type: string
style: form
- 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.
explode: true
in: query
name: via
required: false
schema:
type: string
style: form
- description: An optional identity schema to use for the login flow.
explode: true
in: query
name: identity_schema
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/loginFlow'
description: loginFlow
"303":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"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
x-accepts:
- application/json
/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.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/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`).
explode: true
in: query
name: id
required: true
schema:
type: string
style: form
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
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-low
x-accepts:
- application/json
/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.sh/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.
explode: true
in: query
name: token
required: false
schema:
type: string
style: form
- description: The URL to return to after the logout was completed.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
responses:
"204":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"303":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Update Logout Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-low
x-accepts:
- application/json
/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":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"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
x-content-type: application/json
x-accepts:
- application/json
/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.
explode: false
in: header
name: cookie
required: false
schema:
type: string
style: simple
- description: |-
Return to URL
The URL to which the browser should be redirected to after the logout
has been performed.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
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
x-accepts:
- application/json
/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`).
explode: true
in: query
name: flow
required: true
schema:
type: string
style: form
- 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.
explode: true
in: query
name: token
required: false
schema:
type: string
style: form
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
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":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"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-high
x-content-type: application/json
x-accepts:
- application/json
/self-service/recovery/api:
get:
description: |-
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.
On an existing recovery flow, use the `getRecoveryFlow` API endpoint.
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](../self-service/flows/account-recovery).
operationId: createNativeRecoveryFlow
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/recoveryFlow'
description: recoveryFlow
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Recovery Flow for Native Apps
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/self-service/recovery/browser:
get:
description: |-
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.
If this endpoint is called via an AJAX request, the response contains the recovery flow without any redirects
or a 400 bad request error if the user is already authenticated.
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 Account Recovery Documentation](../self-service/flows/account-recovery).
operationId: createBrowserRecoveryFlow
parameters:
- description: The URL to return the browser to after the flow was completed.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/recoveryFlow'
description: recoveryFlow
"303":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Recovery Flow for Browsers
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/self-service/recovery/flows:
get:
description: |-
This endpoint returns a recovery 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('/recovery', async function (req, res) {
const flow = await client.getRecoveryFlow(req.header('Cookie'), req.query['flow'])
res.render('recovery', flow)
})
```
More information can be found at [Ory Kratos Account Recovery Documentation](../self-service/flows/account-recovery).
operationId: getRecoveryFlow
parameters:
- description: |-
The Flow ID
The value for this parameter comes from `request` URL Query parameter sent to your
application (e.g. `/recovery?flow=abcde`).
explode: true
in: query
name: id
required: true
schema:
type: string
style: form
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/recoveryFlow'
description: recoveryFlow
"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 Recovery Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-low
x-accepts:
- application/json
/self-service/registration:
post:
description: |-
Use this endpoint to complete a registration flow by sending an identity's traits and password. This endpoint
behaves differently for API and browser flows.
API flows expect `application/json` to be sent in the body and respond with
HTTP 200 and a application/json body with the created identity success - if the session hook is configured the
`session` and `session_token` will also be included;
HTTP 410 if the original flow expired with the appropriate error messages set and optionally a `use_flow_id` parameter in the body;
HTTP 400 on form validation errors.
Browser flows expect a Content-Type of `application/x-www-form-urlencoded` or `application/json` to be sent in the body and respond with
a HTTP 303 redirect to the post/after registration URL or the `return_to` value if it was set and if the registration succeeded;
a HTTP 303 redirect to the registration UI URL with the flow ID containing the validation errors otherwise.
Browser flows with an accept header of `application/json` will not redirect but instead respond with
HTTP 200 and a application/json body with the signed in identity and a `Set-Cookie` header on success;
HTTP 303 redirect to a fresh login flow if the original flow expired with the appropriate error messages set;
HTTP 400 on form validation errors.
If this endpoint is called with `Accept: application/json` in the header, the response contains the flow without a redirect. In the
case of an error, the `error.id` of the JSON response body can be one of:
`session_already_available`: The user is already signed in.
`security_csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
`security_identity_mismatch`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
`browser_location_change_required`: Usually sent when an AJAX request indicates that the browser needs to open a specific URL.
Most likely used in Social Sign In flows.
More information can be found at [Ory Kratos User Login](https://www.ory.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-registration).
operationId: updateRegistrationFlow
parameters:
- description: |-
The Registration Flow ID
The value for this parameter comes from `flow` URL Query parameter sent to your
application (e.g. `/registration?flow=abcde`).
explode: true
in: query
name: flow
required: true
schema:
type: string
style: form
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updateRegistrationFlowBody'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/updateRegistrationFlowBody'
required: true
x-originalParamName: Body
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/successfulNativeRegistration'
description: successfulNativeRegistration
"303":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/registrationFlow'
description: registrationFlow
"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 Registration Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-high
x-content-type: application/json
x-accepts:
- application/json
/self-service/registration/api:
get:
description: |-
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=`.
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.
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.
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.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-registration).
operationId: createNativeRegistrationFlow
parameters:
- 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.
explode: true
in: query
name: return_session_token_exchange_code
required: false
schema:
type: boolean
style: form
- description: The URL to return the browser to after the flow was completed.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
- description: |-
An optional organization ID that should be used to register this user.
This parameter is only effective in the Ory Network.
explode: true
in: query
name: organization
required: false
schema:
type: string
style: form
- description: An optional identity schema to use for the registration flow.
explode: true
in: query
name: identity_schema
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/registrationFlow'
description: registrationFlow
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Registration Flow for Native Apps
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/self-service/registration/browser:
get:
description: |-
This endpoint initializes a browser-based user registration 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.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`.
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.
`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!
If this endpoint is called via an AJAX request, the response contains the registration flow without a redirect.
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.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-registration).
operationId: createBrowserRegistrationFlow
parameters:
- description: The URL to return the browser to after the flow was completed.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
- description: |-
Ory OAuth 2.0 Login Challenge.
If set will cooperate with Ory OAuth2 and OpenID to act as an OAuth2 server / OpenID Provider.
The value for this parameter comes from `login_challenge` URL Query parameter sent to your
application (e.g. `/registration?login_challenge=abcde`).
This feature is compatible with Ory Hydra when not running on the Ory Network.
explode: true
in: query
name: login_challenge
required: false
schema:
type: string
style: form
- description: |-
The URL to return the browser to after the verification flow was completed.
After the registration flow is completed, the user will be sent a verification email.
Upon completing the verification flow, this URL will be used to override the default
`selfservice.flows.verification.after.default_redirect_to` value.
explode: true
in: query
name: after_verification_return_to
required: false
schema:
type: string
style: form
- description: |-
An optional organization ID that should be used to register this user.
This parameter is only effective in the Ory Network.
explode: true
in: query
name: organization
required: false
schema:
type: string
style: form
- description: An optional identity schema to use for the registration flow.
explode: true
in: query
name: identity_schema
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/registrationFlow'
description: registrationFlow
"303":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Registration Flow for Browsers
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/self-service/registration/flows:
get:
description: |-
This endpoint returns a registration 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('/registration', async function (req, res) {
const flow = await client.getRegistrationFlow(req.header('cookie'), req.query['flow'])
res.render('registration', 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.sh/docs/kratos/self-service/flows/user-login) and [User Registration Documentation](https://www.ory.sh/docs/kratos/self-service/flows/user-registration).
operationId: getRegistrationFlow
parameters:
- description: |-
The Registration Flow ID
The value for this parameter comes from `flow` URL Query parameter sent to your
application (e.g. `/registration?flow=abcde`).
explode: true
in: query
name: id
required: true
schema:
type: string
style: form
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/registrationFlow'
description: registrationFlow
"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 Registration Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-low
x-accepts:
- application/json
/self-service/settings:
post:
description: |-
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 303 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 or the session's AAL is too low.
Implies that the user needs to re-authenticate.
Browser flows without HTTP Header `Accept` or with `Accept: text/*` respond with
a HTTP 303 redirect to the post/after settings URL or the `return_to` value if it was set and if the flow succeeded;
a HTTP 303 redirect to the Settings UI URL with the flow ID containing the validation errors otherwise.
a HTTP 303 redirect to the login endpoint when `selfservice.flows.settings.privileged_session_max_age` was reached or the session's AAL is too low.
Browser flows with HTTP Header `Accept: application/json` 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 401 when the endpoint is called without a valid session cookie.
HTTP 403 when the page is accessed without a session cookie or the session's AAL is too low.
HTTP 400 on form validation errors.
Depending on your configuration this endpoint might return a 403 error if the session has a lower Authenticator
Assurance Level (AAL) than is possible for the identity. This can happen if the identity has password + webauthn
credentials (which would result in AAL2) but the session has only AAL1. If this error occurs, ask the user
to sign in with the second factor (happens automatically for server-side browser flows) or change the configuration.
If this endpoint is called with a `Accept: application/json` HTTP 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_refresh_required`: The identity requested to change something that needs a privileged session. Redirect
the identity to the login init endpoint with query parameters `?refresh=true&return_to=`,
or initiate a refresh login flow otherwise.
`security_csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
`session_inactive`: No Ory Session was found - sign in a user first.
`security_identity_mismatch`: The flow was interrupted with `session_refresh_required` but apparently some other
identity logged in instead.
`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 Settings & Profile Management Documentation](../self-service/flows/user-settings).
operationId: updateSettingsFlow
parameters:
- description: |-
The Settings Flow ID
The value for this parameter comes from `flow` URL Query parameter sent to your
application (e.g. `/settings?flow=abcde`).
explode: true
in: query
name: flow
required: true
schema:
type: string
style: form
- description: The Session Token of the Identity performing the settings flow.
explode: false
in: header
name: X-Session-Token
required: false
schema:
type: string
style: simple
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updateSettingsFlowBody'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/updateSettingsFlowBody'
required: true
x-originalParamName: Body
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/settingsFlow'
description: settingsFlow
"303":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/settingsFlow'
description: settingsFlow
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"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
security:
- sessionToken: []
summary: Complete Settings Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-high
x-content-type: application/json
x-accepts:
- application/json
/self-service/settings/api:
get:
description: |-
This endpoint initiates a settings flow for API clients such as mobile devices, smart TVs, and so on.
You must provide a valid Ory Kratos Session Token for this endpoint to respond with HTTP 200 OK.
To fetch an existing settings flow call `/self-service/settings/flows?flow=`.
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.
Depending on your configuration this endpoint might return a 403 error if the session has a lower Authenticator
Assurance Level (AAL) than is possible for the identity. This can happen if the identity has password + webauthn
credentials (which would result in AAL2) but the session has only AAL1. If this error occurs, ask the user
to sign in with the second factor or change the configuration.
In the case of an error, the `error.id` of the JSON response body can be one of:
`security_csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
`session_inactive`: No Ory Session was found - sign in a user first.
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 Settings & Profile Management Documentation](../self-service/flows/user-settings).
operationId: createNativeSettingsFlow
parameters:
- description: The Session Token of the Identity performing the settings flow.
explode: false
in: header
name: X-Session-Token
required: false
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/settingsFlow'
description: settingsFlow
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Settings Flow for Native Apps
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/self-service/settings/browser:
get:
description: |-
This endpoint initializes a browser-based user settings flow. Once initialized, the browser will be redirected to
`selfservice.flows.settings.ui_url` with the flow ID set as the query parameter `?flow=`. If no valid
Ory Kratos Session Cookie is included in the request, a login flow will be initialized.
If this endpoint is opened as a link in the browser, it will be redirected to
`selfservice.flows.settings.ui_url` with the flow ID set as the query parameter `?flow=`. If no valid user session
was set, the browser will be redirected to the login endpoint.
If this endpoint is called via an AJAX request, the response contains the settings flow without any redirects
or a 401 forbidden error if no valid session was set.
Depending on your configuration this endpoint might return a 403 error if the session has a lower Authenticator
Assurance Level (AAL) than is possible for the identity. This can happen if the identity has password + webauthn
credentials (which would result in AAL2) but the session has only AAL1. If this error occurs, ask the user
to sign in with the second factor (happens automatically for server-side browser flows) or change the configuration.
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:
`security_csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
`session_inactive`: No Ory Session was found - sign in a user first.
`security_identity_mismatch`: The requested `?return_to` address is not allowed to be used. Adjust this in the configuration!
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 Settings & Profile Management Documentation](../self-service/flows/user-settings).
operationId: createBrowserSettingsFlow
parameters:
- description: The URL to return the browser to after the flow was completed.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/settingsFlow'
description: settingsFlow
"303":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Settings Flow for Browsers
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/self-service/settings/flows:
get:
description: |-
When accessing this endpoint through Ory Kratos' Public API you must ensure that either the Ory Kratos Session Cookie
or the Ory Kratos Session Token are set.
Depending on your configuration this endpoint might return a 403 error if the session has a lower Authenticator
Assurance Level (AAL) than is possible for the identity. This can happen if the identity has password + webauthn
credentials (which would result in AAL2) but the session has only AAL1. If this error occurs, ask the user
to sign in with the second factor or change the configuration.
You can access this endpoint without credentials when using Ory Kratos' Admin API.
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:
`security_csrf_violation`: Unable to fetch the flow because a CSRF violation occurred.
`session_inactive`: No Ory Session was found - sign in a user first.
`security_identity_mismatch`: The flow was interrupted with `session_refresh_required` but apparently some other
identity logged in instead.
More information can be found at [Ory Kratos User Settings & Profile Management Documentation](../self-service/flows/user-settings).
operationId: getSettingsFlow
parameters:
- description: |-
ID is the Settings Flow ID
The value for this parameter comes from `flow` URL Query parameter sent to your
application (e.g. `/settings?flow=abcde`).
explode: true
in: query
name: id
required: true
schema:
type: string
style: form
- description: |-
The Session Token
When using the SDK in an app without a browser, please include the
session token here.
explode: false
in: header
name: X-Session-Token
required: false
schema:
type: string
style: simple
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/settingsFlow'
description: settingsFlow
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"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 Settings Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-low
x-accepts:
- application/json
/self-service/verification:
post:
description: |-
Use this endpoint to complete a verification 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 verification 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 Verification UI URL with the Verification Flow ID appended.
`sent_email` is the success state after `choose_method` when using the `link` method and allows the user to request another verification 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 verification 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 Verification UI URL with
a new Verification Flow ID which contains an error message that the verification link was invalid.
More information can be found at [Ory Kratos Email and Phone Verification Documentation](https://www.ory.sh/docs/kratos/self-service/flows/verify-email-account-activation).
operationId: updateVerificationFlow
parameters:
- description: |-
The Verification Flow ID
The value for this parameter comes from `flow` URL Query parameter sent to your
application (e.g. `/verification?flow=abcde`).
explode: true
in: query
name: flow
required: true
schema:
type: string
style: form
- description: |-
Verification Token
The verification token which completes the verification 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.
explode: true
in: query
name: token
required: false
schema:
type: string
style: form
- 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.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updateVerificationFlowBody'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/updateVerificationFlowBody'
required: true
x-originalParamName: Body
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/verificationFlow'
description: verificationFlow
"303":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/verificationFlow'
description: verificationFlow
"410":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Complete Verification Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-high
x-content-type: application/json
x-accepts:
- application/json
/self-service/verification/api:
get:
description: |-
This endpoint initiates a verification flow for API clients such as mobile devices, smart TVs, and so on.
To fetch an existing verification flow call `/self-service/verification/flows?flow=`.
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 Email and Phone Verification Documentation](https://www.ory.sh/docs/kratos/self-service/flows/verify-email-account-activation).
operationId: createNativeVerificationFlow
parameters:
- description: |-
A URL contained in the return_to key of the verification flow.
This piece of data has no effect on the actual logic of the flow and is purely informational.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/verificationFlow'
description: verificationFlow
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Verification Flow for Native Apps
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/self-service/verification/browser:
get:
description: |-
This endpoint initializes a browser-based account verification flow. Once initialized, the browser will be redirected to
`selfservice.flows.verification.ui_url` with the flow ID set as the query parameter `?flow=`.
If this endpoint is called via an AJAX request, the response contains the recovery flow without any redirects.
This endpoint is NOT INTENDED for API clients and only works with browsers (Chrome, Firefox, ...).
More information can be found at [Ory Kratos Email and Phone Verification Documentation](https://www.ory.sh/docs/kratos/self-service/flows/verify-email-account-activation).
operationId: createBrowserVerificationFlow
parameters:
- description: The URL to return the browser to after the flow was completed.
explode: true
in: query
name: return_to
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/verificationFlow'
description: verificationFlow
"303":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Create Verification Flow for Browser Clients
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/self-service/verification/flows:
get:
description: |-
This endpoint returns a verification 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('/recovery', async function (req, res) {
const flow = await client.getVerificationFlow(req.header('cookie'), req.query['flow'])
res.render('verification', flow)
})
```
More information can be found at [Ory Kratos Email and Phone Verification Documentation](https://www.ory.sh/docs/kratos/self-service/flows/verify-email-account-activation).
operationId: getVerificationFlow
parameters:
- description: |-
The Flow ID
The value for this parameter comes from `request` URL Query parameter sent to your
application (e.g. `/verification?flow=abcde`).
explode: true
in: query
name: id
required: true
schema:
type: string
style: form
- description: |-
HTTP Cookies
When using the SDK on the server side you must include the HTTP Cookie Header
originally sent to your HTTP handler here.
explode: false
in: header
name: cookie
required: false
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/verificationFlow'
description: verificationFlow
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Get Verification Flow
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-low
x-accepts:
- application/json
/sessions:
delete:
description: |-
Calling this endpoint invalidates all except the current session that belong to the logged-in user.
Session data are not deleted.
operationId: disableMyOtherSessions
parameters:
- description: Set the Session Token when calling from non-browser clients.
A session token has a format of `MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj`.
explode: false
in: header
name: X-Session-Token
required: false
schema:
type: string
style: simple
- description: |-
Set the Cookie Header. This is especially useful when calling this endpoint from a server-side application. In that
scenario you must include the HTTP Cookie Header which originally was included in the request to your server.
An example of a session in the HTTP Cookie Header is: `ory_kratos_session=a19iOVAbdzdgl70Rq1QZmrKmcjDtdsviCTZx7m9a9yHIUS8Wa9T7hvqyGTsLHi6Qifn2WUfpAKx9DWp0SJGleIn9vh2YF4A16id93kXFTgIgmwIOvbVAScyrx7yVl6bPZnCx27ec4WQDtaTewC1CpgudeDV2jQQnSaCP6ny3xa8qLH-QUgYqdQuoA_LF1phxgRCUfIrCLQOkolX5nv3ze_f==`.
It is ok if more than one cookie are included here as all other cookies will be ignored.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/deleteMySessionsCount'
description: deleteMySessionsCount
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Disable my other sessions
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-high
x-accepts:
- application/json
get:
description: |-
This endpoints returns all other active sessions that belong to the logged-in user.
The current session can be retrieved by calling the `/sessions/whoami` endpoint.
operationId: listMySessions
parameters:
- description: |-
Deprecated Items per Page
DEPRECATED: Please use `page_token` instead. This parameter will be removed in the future.
This is the number of items per page.
explode: true
in: query
name: per_page
required: false
schema:
default: 250
format: int64
maximum: 1000
minimum: 1
type: integer
style: form
- description: |-
Deprecated Pagination Page
DEPRECATED: Please use `page_token` instead. This parameter will be removed in the future.
This value is currently an integer, but it is not sequential. The value is not the page number, but a
reference. The next page can be any number and some numbers might return an empty list.
For example, page 2 might not follow after page 1. And even if page 3 and 5 exist, but page 4 might not exist.
The first page can be retrieved by omitting this parameter. Following page pointers will be returned in the
`Link` header.
explode: true
in: query
name: page
required: false
schema:
format: int64
type: integer
style: form
- description: |-
Page Size
This is the number of items per page to return. For details on pagination please head over to the
[pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_size
required: false
schema:
default: 250
format: int64
maximum: 500
minimum: 1
type: integer
style: form
- description: |-
Next Page Token
The next page token. For details on pagination please head over to the
[pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
explode: true
in: query
name: page_token
required: false
schema:
type: string
style: form
- description: Set the Session Token when calling from non-browser clients.
A session token has a format of `MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj`.
explode: false
in: header
name: X-Session-Token
required: false
schema:
type: string
style: simple
- description: |-
Set the Cookie Header. This is especially useful when calling this endpoint from a server-side application. In that
scenario you must include the HTTP Cookie Header which originally was included in the request to your server.
An example of a session in the HTTP Cookie Header is: `ory_kratos_session=a19iOVAbdzdgl70Rq1QZmrKmcjDtdsviCTZx7m9a9yHIUS8Wa9T7hvqyGTsLHi6Qifn2WUfpAKx9DWp0SJGleIn9vh2YF4A16id93kXFTgIgmwIOvbVAScyrx7yVl6bPZnCx27ec4WQDtaTewC1CpgudeDV2jQQnSaCP6ny3xa8qLH-QUgYqdQuoA_LF1phxgRCUfIrCLQOkolX5nv3ze_f==`.
It is ok if more than one cookie are included here as all other cookies will be ignored.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/session'
type: array
description: List My Session Response
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Get My Active Sessions
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/sessions/token-exchange:
get:
operationId: exchangeSessionToken
parameters:
- description: The part of the code return when initializing the flow.
explode: true
in: query
name: init_code
required: true
schema:
type: string
style: form
- description: The part of the code returned by the return_to URL.
explode: true
in: query
name: return_to_code
required: true
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/successfulNativeLogin'
description: successfulNativeLogin
"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: Exchange Session Token
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-medium
x-accepts:
- application/json
/sessions/whoami:
get:
description: |-
Uses the HTTP Headers in the GET request to determine (e.g. by using checking the cookies) who is authenticated.
Returns a session object in the body or 401 if the credentials are invalid or no credentials were sent.
When the request it successful it adds the user ID to the 'X-Kratos-Authenticated-Identity-Id' header
in the response.
If you call this endpoint from a server-side application, you must forward the HTTP Cookie Header to this endpoint:
```js
pseudo-code example
router.get('/protected-endpoint', async function (req, res) {
const session = await client.toSession(undefined, req.header('cookie'))
console.log(session)
})
```
When calling this endpoint from a non-browser application (e.g. mobile app) you must include the session token:
```js
pseudo-code example
...
const session = await client.toSession("the-session-token")
console.log(session)
```
When using a token template, the token is included in the `tokenized` field of the session.
```js
pseudo-code example
...
const session = await client.toSession("the-session-token", { tokenize_as: "example-jwt-template" })
console.log(session.tokenized) // The JWT
```
Depending on your configuration this endpoint might return a 403 status code if the session has a lower Authenticator
Assurance Level (AAL) than is possible for the identity. This can happen if the identity has password + webauthn
credentials (which would result in AAL2) but the session has only AAL1. If this error occurs, ask the user
to sign in with the second factor or change the configuration.
This endpoint is useful for:
AJAX calls. Remember to send credentials and set up CORS correctly!
Reverse proxies and API Gateways
Server-side calls - use the `X-Session-Token` header!
This endpoint authenticates users by checking:
if the `Cookie` HTTP header was set containing an Ory Kratos Session Cookie;
if the `Authorization: bearer ` HTTP header was set with a valid Ory Kratos Session Token;
if the `X-Session-Token` HTTP header was set with a valid Ory Kratos Session Token.
If none of these headers are set or the cookie or token are invalid, the endpoint returns a HTTP 401 status code.
As explained above, this request may fail due to several reasons. The `error.id` can be one of:
`session_inactive`: No active session was found in the request (e.g. no Ory Session Cookie / Ory Session Token).
`session_aal2_required`: An active session was found but it does not fulfil the Authenticator Assurance Level, implying that the session must (e.g.) authenticate the second factor.
operationId: toSession
parameters:
- description: Set the Session Token when calling from non-browser clients.
A session token has a format of `MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj`.
example: MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj
explode: false
in: header
name: X-Session-Token
required: false
schema:
type: string
style: simple
- description: |-
Set the Cookie Header. This is especially useful when calling this endpoint from a server-side application. In that
scenario you must include the HTTP Cookie Header which originally was included in the request to your server.
An example of a session in the HTTP Cookie Header is: `ory_kratos_session=a19iOVAbdzdgl70Rq1QZmrKmcjDtdsviCTZx7m9a9yHIUS8Wa9T7hvqyGTsLHi6Qifn2WUfpAKx9DWp0SJGleIn9vh2YF4A16id93kXFTgIgmwIOvbVAScyrx7yVl6bPZnCx27ec4WQDtaTewC1CpgudeDV2jQQnSaCP6ny3xa8qLH-QUgYqdQuoA_LF1phxgRCUfIrCLQOkolX5nv3ze_f==`.
It is ok if more than one cookie are included here as all other cookies will be ignored.
example: ory_session=a19iOVAbdzdgl70Rq1QZmrKmcjDtdsviCTZx7m9a9yHIUS8Wa9T7hvqyGTsLHi6Qifn2WUfpAKx9DWp0SJGleIn9vh2YF4A16id93kXFTgIgmwIOvbVAScyrx7yVl6bPZnCx27ec4WQDtaTewC1CpgudeDV2jQQnSaCP6ny3xa8qLH-QUgYqdQuoA_LF1phxgRCUfIrCLQOkolX5nv3ze_f==
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
- description: |-
Returns the session additionally as a token (such as a JWT)
The value of this parameter has to be a valid, configured Ory Session token template. For more information head over to [the documentation](http://ory.sh/docs/identities/session-to-jwt-cors).
explode: true
in: query
name: tokenize_as
required: false
schema:
type: string
style: form
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/session'
description: session
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Check Who the Current HTTP Session Belongs To
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-low
x-accepts:
- application/json
/sessions/{id}:
delete:
description: |-
Calling this endpoint invalidates the specified session. The current session cannot be revoked.
Session data are not deleted.
operationId: disableMySession
parameters:
- description: ID is the session's ID.
explode: false
in: path
name: id
required: true
schema:
type: string
style: simple
- description: Set the Session Token when calling from non-browser clients.
A session token has a format of `MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj`.
explode: false
in: header
name: X-Session-Token
required: false
schema:
type: string
style: simple
- description: |-
Set the Cookie Header. This is especially useful when calling this endpoint from a server-side application. In that
scenario you must include the HTTP Cookie Header which originally was included in the request to your server.
An example of a session in the HTTP Cookie Header is: `ory_kratos_session=a19iOVAbdzdgl70Rq1QZmrKmcjDtdsviCTZx7m9a9yHIUS8Wa9T7hvqyGTsLHi6Qifn2WUfpAKx9DWp0SJGleIn9vh2YF4A16id93kXFTgIgmwIOvbVAScyrx7yVl6bPZnCx27ec4WQDtaTewC1CpgudeDV2jQQnSaCP6ny3xa8qLH-QUgYqdQuoA_LF1phxgRCUfIrCLQOkolX5nv3ze_f==`.
It is ok if more than one cookie are included here as all other cookies will be ignored.
explode: false
in: header
name: Cookie
required: false
schema:
type: string
style: simple
responses:
"204":
description: "Empty responses are sent when, for example, resources are\
\ deleted. The HTTP status code for empty responses is typically 204."
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
default:
content:
application/json:
schema:
$ref: '#/components/schemas/errorGeneric'
description: errorGeneric
summary: Disable one of my sessions
tags:
- frontend
x-ory-ratelimit-bucket: kratos-public-high
x-accepts:
- application/json
/version:
get:
description: |-
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.
operationId: getVersion
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/getVersion_200_response'
description: Returns the Ory Kratos version.
summary: Return Running Software Version.
tags:
- metadata
x-accepts:
- application/json
components:
responses:
emptyResponse:
description: "Empty responses are sent when, for example, resources are deleted.\
\ The HTTP status code for empty responses is typically 204."
identitySchemas:
content:
application/json:
schema:
$ref: '#/components/schemas/identitySchemas'
description: List Identity JSON Schemas Response
listCourierMessages:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/message'
type: array
description: Paginated Courier Message List Response
listIdentities:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/identity'
type: array
description: Paginated Identity List Response
listIdentitySessions:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/session'
type: array
description: List Identity Sessions Response
listMySessions:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/session'
type: array
description: List My Session Response
listSessions:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/session'
type: array
description: |-
Session List Response
The response given when listing sessions in an administrative context.
schemas:
CodeChannel:
type: string
DefaultError: {}
Duration:
description: |-
A Duration represents the elapsed time between two instants
as an int64 nanosecond count. The representation limits the
largest representable duration to approximately 290 years.
format: int64
type: integer
ID:
format: int64
type: integer
JSONRawMessage:
title: "JSONRawMessage represents a json.RawMessage that works well with JSON,\
\ SQL, and Swagger."
type: object
NullBool:
nullable: true
type: boolean
NullInt:
nullable: true
type: integer
NullString:
nullable: true
type: string
NullTime:
format: date-time
nullable: true
type: string
NullUUID:
format: uuid4
nullable: true
type: string
OAuth2Client:
example:
metadata: ""
token_endpoint_auth_signing_alg: token_endpoint_auth_signing_alg
client_uri: client_uri
jwt_bearer_grant_access_token_lifespan: jwt_bearer_grant_access_token_lifespan
jwks: ""
logo_uri: logo_uri
created_at: 2000-01-23T04:56:07.000+00:00
registration_client_uri: registration_client_uri
allowed_cors_origins:
- allowed_cors_origins
- allowed_cors_origins
refresh_token_grant_access_token_lifespan: refresh_token_grant_access_token_lifespan
registration_access_token: registration_access_token
client_id: client_id
token_endpoint_auth_method: token_endpoint_auth_method
userinfo_signed_response_alg: userinfo_signed_response_alg
authorization_code_grant_id_token_lifespan: authorization_code_grant_id_token_lifespan
authorization_code_grant_refresh_token_lifespan: authorization_code_grant_refresh_token_lifespan
client_credentials_grant_access_token_lifespan: client_credentials_grant_access_token_lifespan
updated_at: 2000-01-23T04:56:07.000+00:00
scope: scope
request_uris:
- request_uris
- request_uris
client_secret: client_secret
backchannel_logout_session_required: true
backchannel_logout_uri: backchannel_logout_uri
client_name: client_name
policy_uri: policy_uri
owner: owner
skip_consent: true
audience:
- audience
- audience
authorization_code_grant_access_token_lifespan: authorization_code_grant_access_token_lifespan
post_logout_redirect_uris:
- post_logout_redirect_uris
- post_logout_redirect_uris
grant_types:
- grant_types
- grant_types
subject_type: subject_type
refresh_token_grant_refresh_token_lifespan: refresh_token_grant_refresh_token_lifespan
redirect_uris:
- redirect_uris
- redirect_uris
sector_identifier_uri: sector_identifier_uri
frontchannel_logout_session_required: true
frontchannel_logout_uri: frontchannel_logout_uri
skip_logout_consent: true
refresh_token_grant_id_token_lifespan: refresh_token_grant_id_token_lifespan
implicit_grant_id_token_lifespan: implicit_grant_id_token_lifespan
client_secret_expires_at: 0
implicit_grant_access_token_lifespan: implicit_grant_access_token_lifespan
access_token_strategy: access_token_strategy
jwks_uri: jwks_uri
request_object_signing_alg: request_object_signing_alg
tos_uri: tos_uri
contacts:
- contacts
- contacts
response_types:
- response_types
- response_types
properties:
access_token_strategy:
description: "OAuth 2.0 Access Token Strategy AccessTokenStrategy is the\
\ strategy used to generate access tokens. Valid options are `jwt` and\
\ `opaque`. `jwt` is a bad idea, see https://www.ory.sh/docs/hydra/advanced#json-web-tokens\
\ Setting the stragegy here overrides the global setting in `strategies.access_token`."
type: string
allowed_cors_origins:
items:
type: string
type: array
audience:
items:
type: string
type: array
authorization_code_grant_access_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
authorization_code_grant_id_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
authorization_code_grant_refresh_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
backchannel_logout_session_required:
description: "OpenID Connect Back-Channel Logout Session Required Boolean\
\ value specifying whether the RP requires that a sid (session ID) Claim\
\ be included in the Logout Token to identify the RP session with the\
\ OP when the backchannel_logout_uri is used. If omitted, the default\
\ value is false."
type: boolean
backchannel_logout_uri:
description: OpenID Connect Back-Channel Logout URI RP URL that will cause
the RP to log itself out when sent a Logout Token by the OP.
type: string
client_credentials_grant_access_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
client_id:
description: "OAuth 2.0 Client ID The ID is immutable. If no ID is provided,\
\ a UUID4 will be generated."
type: string
client_name:
description: OAuth 2.0 Client Name The human-readable name of the client
to be presented to the end-user during authorization.
type: string
client_secret:
description: "OAuth 2.0 Client Secret The secret will be included in the\
\ create request as cleartext, and then never again. The secret is kept\
\ in hashed format and is not recoverable once lost."
type: string
client_secret_expires_at:
description: OAuth 2.0 Client Secret Expires At The field is currently
not supported and its value is always 0.
format: int64
type: integer
client_uri:
description: "OAuth 2.0 Client URI ClientURI is a URL string of a web page\
\ providing information about the client. If present, the server SHOULD\
\ display this URL to the end-user in a clickable fashion."
type: string
contacts:
items:
type: string
type: array
created_at:
description: OAuth 2.0 Client Creation Date CreatedAt returns the timestamp
of the client's creation.
format: date-time
type: string
frontchannel_logout_session_required:
description: "OpenID Connect Front-Channel Logout Session Required Boolean\
\ value specifying whether the RP requires that iss (issuer) and sid (session\
\ ID) query parameters be included to identify the RP session with the\
\ OP when the frontchannel_logout_uri is used. If omitted, the default\
\ value is false."
type: boolean
frontchannel_logout_uri:
description: "OpenID Connect Front-Channel Logout URI RP URL that will\
\ cause the RP to log itself out when rendered in an iframe by the OP.\
\ An iss (issuer) query parameter and a sid (session ID) query parameter\
\ MAY be included by the OP to enable the RP to validate the request and\
\ to determine which of the potentially multiple sessions is to be logged\
\ out; if either is included, both MUST be."
type: string
grant_types:
items:
type: string
type: array
implicit_grant_access_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
implicit_grant_id_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
jwks:
description: "OAuth 2.0 Client JSON Web Key Set Client's JSON Web Key Set\
\ [JWK] document, passed by value. The semantics of the jwks parameter\
\ are the same as the jwks_uri parameter, other than that the JWK Set\
\ is passed by value, rather than by reference. This parameter is intended\
\ only to be used by Clients that, for some reason, are unable to use\
\ the jwks_uri parameter, for instance, by native applications that might\
\ not have a location to host the contents of the JWK Set. If a Client\
\ can use jwks_uri, it MUST NOT use jwks. One significant downside of\
\ jwks is that it does not enable key rotation (which jwks_uri does, as\
\ described in Section 10 of OpenID Connect Core 1.0 [OpenID.Core]). The\
\ jwks_uri and jwks parameters MUST NOT be used together."
jwks_uri:
description: "OAuth 2.0 Client JSON Web Key Set URL URL for the Client's\
\ JSON Web Key Set [JWK] document. If the Client signs requests to the\
\ Server, it contains the signing key(s) the Server uses to validate signatures\
\ from the Client. The JWK Set MAY also contain the Client's encryption\
\ keys(s), which are used by the Server to encrypt responses to the Client.\
\ When both signing and encryption keys are made available, a use (Key\
\ Use) parameter value is REQUIRED for all keys in the referenced JWK\
\ Set to indicate each key's intended usage. Although some algorithms\
\ allow the same key to be used for both signatures and encryption, doing\
\ so is NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY\
\ be used to provide X.509 representations of keys provided. When used,\
\ the bare key values MUST still be present and MUST match those in the\
\ certificate."
type: string
jwt_bearer_grant_access_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
logo_uri:
description: OAuth 2.0 Client Logo URI A URL string referencing the client's
logo.
type: string
metadata: {}
owner:
description: OAuth 2.0 Client Owner Owner is a string identifying the owner
of the OAuth 2.0 Client.
type: string
policy_uri:
description: "OAuth 2.0 Client Policy URI PolicyURI is a URL string that\
\ points to a human-readable privacy policy document that describes how\
\ the deployment organization collects, uses, retains, and discloses personal\
\ data."
type: string
post_logout_redirect_uris:
items:
type: string
type: array
redirect_uris:
items:
type: string
type: array
refresh_token_grant_access_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
refresh_token_grant_id_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
refresh_token_grant_refresh_token_lifespan:
description: "Specify a time duration in milliseconds, seconds, minutes,\
\ hours."
type: string
registration_access_token:
description: "OpenID Connect Dynamic Client Registration Access Token RegistrationAccessToken\
\ can be used to update, get, or delete the OAuth2 Client. It is sent\
\ when creating a client using Dynamic Client Registration."
type: string
registration_client_uri:
description: "OpenID Connect Dynamic Client Registration URL RegistrationClientURI\
\ is the URL used to update, get, or delete the OAuth2 Client."
type: string
request_object_signing_alg:
description: "OpenID Connect Request Object Signing Algorithm JWS [JWS]\
\ alg algorithm [JWA] that MUST be used for signing Request Objects sent\
\ to the OP. All Request Objects from this Client MUST be rejected, if\
\ not signed with this algorithm."
type: string
request_uris:
items:
type: string
type: array
response_types:
items:
type: string
type: array
scope:
description: "OAuth 2.0 Client Scope Scope is a string containing a space-separated\
\ list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749])\
\ that the client can use when requesting access tokens."
type: string
sector_identifier_uri:
description: OpenID Connect Sector Identifier URI URL using the https scheme
to be used in calculating Pseudonymous Identifiers by the OP. The URL
references a file with a single JSON array of redirect_uri values.
type: string
skip_consent:
description: SkipConsent skips the consent screen for this client. This
field can only be set from the admin API.
type: boolean
skip_logout_consent:
description: SkipLogoutConsent skips the logout consent screen for this
client. This field can only be set from the admin API.
type: boolean
subject_type:
description: OpenID Connect Subject Type The `subject_types_supported`
Discovery parameter contains a list of the supported subject_type values
for this server. Valid types include `pairwise` and `public`.
type: string
token_endpoint_auth_method:
description: "OAuth 2.0 Token Endpoint Authentication Method Requested\
\ Client Authentication method for the Token Endpoint. The options are:\
\ `client_secret_basic`: (default) Send `client_id` and `client_secret`\
\ as `application/x-www-form-urlencoded` encoded in the HTTP Authorization\
\ header. `client_secret_post`: Send `client_id` and `client_secret` as\
\ `application/x-www-form-urlencoded` in the HTTP body. `private_key_jwt`:\
\ Use JSON Web Tokens to authenticate the client. `none`: Used for public\
\ clients (native apps, mobile apps) which can not have secrets."
type: string
token_endpoint_auth_signing_alg:
description: OAuth 2.0 Token Endpoint Signing Algorithm Requested Client
Authentication signing algorithm for the Token Endpoint.
type: string
tos_uri:
description: OAuth 2.0 Client Terms of Service URI A URL string pointing
to a human-readable terms of service document for the client that describes
a contractual relationship between the end-user and the client that the
end-user accepts when authorizing the client.
type: string
updated_at:
description: OAuth 2.0 Client Last Update Date UpdatedAt returns the timestamp
of the last update.
format: date-time
type: string
userinfo_signed_response_alg:
description: "OpenID Connect Request Userinfo Signed Response Algorithm\
\ JWS alg algorithm [JWA] REQUIRED for signing UserInfo Responses. If\
\ this is specified, the response will be JWT [JWT] serialized, and signed\
\ using JWS. The default, if omitted, is for the UserInfo Response to\
\ return the Claims as a UTF-8 encoded JSON object using the application/json\
\ content-type."
type: string
title: "OAuth2Client OAuth 2.0 Clients are used to perform OAuth 2.0 and OpenID\
\ Connect flows. Usually, OAuth 2.0 clients are generated for applications\
\ which want to consume your OAuth 2.0 or OpenID Connect capabilities."
type: object
OAuth2ConsentRequestOpenIDConnectContext:
description: OAuth2ConsentRequestOpenIDConnectContext struct for OAuth2ConsentRequestOpenIDConnectContext
example:
login_hint: login_hint
ui_locales:
- ui_locales
- ui_locales
id_token_hint_claims:
key: ""
acr_values:
- acr_values
- acr_values
display: display
properties:
acr_values:
description: "ACRValues is the Authentication AuthorizationContext Class\
\ Reference requested in the OAuth 2.0 Authorization request. It is a\
\ parameter defined by OpenID Connect and expresses which level of authentication\
\ (e.g. 2FA) is required. OpenID Connect defines it as follows: > Requested\
\ Authentication AuthorizationContext Class Reference values. Space-separated\
\ string that specifies the acr values that the Authorization Server is\
\ being requested to use for processing this Authentication Request, with\
\ the values appearing in order of preference. The Authentication AuthorizationContext\
\ Class satisfied by the authentication performed is returned as the acr\
\ Claim Value, as specified in Section 2. The acr Claim is requested as\
\ a Voluntary Claim by this parameter."
items:
type: string
type: array
display:
description: "Display is a string value that specifies how the Authorization\
\ Server displays the authentication and consent user interface pages\
\ to the End-User. The defined values are: page: The Authorization Server\
\ SHOULD display the authentication and consent UI consistent with a full\
\ User Agent page view. If the display parameter is not specified, this\
\ is the default display mode. popup: The Authorization Server SHOULD\
\ display the authentication and consent UI consistent with a popup User\
\ Agent window. The popup User Agent window should be of an appropriate\
\ size for a login-focused dialog and should not obscure the entire window\
\ that it is popping up over. touch: The Authorization Server SHOULD display\
\ the authentication and consent UI consistent with a device that leverages\
\ a touch interface. wap: The Authorization Server SHOULD display the\
\ authentication and consent UI consistent with a \\\"feature phone\\\"\
\ type display. The Authorization Server MAY also attempt to detect the\
\ capabilities of the User Agent and present an appropriate display."
type: string
id_token_hint_claims:
additionalProperties: {}
description: IDTokenHintClaims are the claims of the ID Token previously
issued by the Authorization Server being passed as a hint about the End-User's
current or past authenticated session with the Client.
type: object
login_hint:
description: LoginHint hints about the login identifier the End-User might
use to log in (if necessary). This hint can be used by an RP if it first
asks the End-User for their e-mail address (or other identifier) and then
wants to pass that value as a hint to the discovered authorization service.
This value MAY also be a phone number in the format specified for the
phone_number Claim. The use of this parameter is optional.
type: string
ui_locales:
description: "UILocales is the End-User'id preferred languages and scripts\
\ for the user interface, represented as a space-separated list of BCP47\
\ [RFC5646] language tag values, ordered by preference. For instance,\
\ the value \\\"fr-CA fr en\\\" represents a preference for French as\
\ spoken in Canada, then French (without a region designation), followed\
\ by English (without a region designation). An error SHOULD NOT result\
\ if some or all of the requested locales are not supported by the OpenID\
\ Provider."
items:
type: string
type: array
type: object
OAuth2LoginChallengeParams:
type: object
OAuth2LoginRequest:
description: OAuth2LoginRequest struct for OAuth2LoginRequest
example:
requested_access_token_audience:
- requested_access_token_audience
- requested_access_token_audience
subject: subject
oidc_context:
login_hint: login_hint
ui_locales:
- ui_locales
- ui_locales
id_token_hint_claims:
key: ""
acr_values:
- acr_values
- acr_values
display: display
challenge: challenge
client:
metadata: ""
token_endpoint_auth_signing_alg: token_endpoint_auth_signing_alg
client_uri: client_uri
jwt_bearer_grant_access_token_lifespan: jwt_bearer_grant_access_token_lifespan
jwks: ""
logo_uri: logo_uri
created_at: 2000-01-23T04:56:07.000+00:00
registration_client_uri: registration_client_uri
allowed_cors_origins:
- allowed_cors_origins
- allowed_cors_origins
refresh_token_grant_access_token_lifespan: refresh_token_grant_access_token_lifespan
registration_access_token: registration_access_token
client_id: client_id
token_endpoint_auth_method: token_endpoint_auth_method
userinfo_signed_response_alg: userinfo_signed_response_alg
authorization_code_grant_id_token_lifespan: authorization_code_grant_id_token_lifespan
authorization_code_grant_refresh_token_lifespan: authorization_code_grant_refresh_token_lifespan
client_credentials_grant_access_token_lifespan: client_credentials_grant_access_token_lifespan
updated_at: 2000-01-23T04:56:07.000+00:00
scope: scope
request_uris:
- request_uris
- request_uris
client_secret: client_secret
backchannel_logout_session_required: true
backchannel_logout_uri: backchannel_logout_uri
client_name: client_name
policy_uri: policy_uri
owner: owner
skip_consent: true
audience:
- audience
- audience
authorization_code_grant_access_token_lifespan: authorization_code_grant_access_token_lifespan
post_logout_redirect_uris:
- post_logout_redirect_uris
- post_logout_redirect_uris
grant_types:
- grant_types
- grant_types
subject_type: subject_type
refresh_token_grant_refresh_token_lifespan: refresh_token_grant_refresh_token_lifespan
redirect_uris:
- redirect_uris
- redirect_uris
sector_identifier_uri: sector_identifier_uri
frontchannel_logout_session_required: true
frontchannel_logout_uri: frontchannel_logout_uri
skip_logout_consent: true
refresh_token_grant_id_token_lifespan: refresh_token_grant_id_token_lifespan
implicit_grant_id_token_lifespan: implicit_grant_id_token_lifespan
client_secret_expires_at: 0
implicit_grant_access_token_lifespan: implicit_grant_access_token_lifespan
access_token_strategy: access_token_strategy
jwks_uri: jwks_uri
request_object_signing_alg: request_object_signing_alg
tos_uri: tos_uri
contacts:
- contacts
- contacts
response_types:
- response_types
- response_types
session_id: session_id
skip: true
request_url: request_url
requested_scope:
- requested_scope
- requested_scope
properties:
challenge:
description: ID is the identifier (\"login challenge\") of the login request.
It is used to identify the session.
type: string
client:
$ref: '#/components/schemas/OAuth2Client'
oidc_context:
$ref: '#/components/schemas/OAuth2ConsentRequestOpenIDConnectContext'
request_url:
description: "RequestURL is the original OAuth 2.0 Authorization URL requested\
\ by the OAuth 2.0 client. It is the URL which initiates the OAuth 2.0\
\ Authorization Code or OAuth 2.0 Implicit flow. This URL is typically\
\ not needed, but might come in handy if you want to deal with additional\
\ request parameters."
type: string
requested_access_token_audience:
items:
type: string
type: array
requested_scope:
items:
type: string
type: array
session_id:
description: SessionID is the login session ID. If the user-agent reuses
a login session (via cookie / remember flag) this ID will remain the same.
If the user-agent did not have an existing authentication session (e.g.
remember is false) this will be a new random value. This value is used
as the \"sid\" parameter in the ID Token and in OIDC Front-/Back- channel
logout. It's value can generally be used to associate consecutive login
requests by a certain user.
type: string
skip:
description: "Skip, if true, implies that the client has requested the same\
\ scopes from the same user previously. If true, you can skip asking the\
\ user to grant the requested scopes, and simply forward the user to the\
\ redirect URL. This feature allows you to update / set session information."
type: boolean
subject:
description: "Subject is the user ID of the end-user that authenticated.\
\ Now, that end user needs to grant or deny the scope requested by the\
\ OAuth 2.0 client. If this value is set and `skip` is true, you MUST\
\ include this subject type when accepting the login request, or the request\
\ will fail."
type: string
type: object
Provider:
example:
domain_hint: domain_hint
login_hint: login_hint
config_url: config_url
fields:
- fields
- fields
nonce: nonce
parameters:
key: parameters
client_id: client_id
properties:
client_id:
description: "The RP's client identifier, issued by the IdP."
type: string
config_url:
description: A full path of the IdP config file.
type: string
domain_hint:
description: |-
By specifying one of domain_hints values provided by the accounts endpoints,
the FedCM dialog selectively shows the specified account.
type: string
fields:
description: |-
Array of strings that specifies the user information ("name", " email",
"picture") that RP needs IdP to share with them.
Note: Field API is supported by Chrome 132 and later.
items:
type: string
type: array
login_hint:
description: |-
By specifying one of login_hints values provided by the accounts endpoints,
the FedCM dialog selectively shows the specified account.
type: string
nonce:
description: |-
A random string to ensure the response is issued for this specific request.
Prevents replay attacks.
type: string
parameters:
additionalProperties:
type: string
description: |-
Custom object that allows to specify additional key-value parameters:
scope: A string value containing additional permissions that RP needs to
request, for example " drive.readonly calendar.readonly"
nonce: A random string to ensure the response is issued for this specific
request. Prevents replay attacks.
Other custom key-value parameters.
Note: parameters is supported from Chrome 132.
type: object
type: object
Time:
format: date-time
type: string
UUID:
format: uuid4
type: string
UpdateFedcmFlowBody:
example:
transient_payload: "{}"
csrf_token: csrf_token
nonce: nonce
token: token
properties:
csrf_token:
description: CSRFToken is the anti-CSRF token.
type: string
nonce:
description: |-
Nonce is the nonce that was used in the `navigator.credentials.get` call. If
specified, it must match the `nonce` claim in the token.
type: string
token:
description: Token contains the result of `navigator.credentials.get`.
type: string
transient_payload:
description: Transient data to pass along to any webhooks.
type: object
required:
- csrf_token
- token
type: object
authenticatorAssuranceLevel:
description: |-
The authenticator assurance level can be one of "aal1", "aal2", or "aal3". A higher number means that it is harder
for an attacker to compromise the account.
Generally, "aal1" implies that one authentication factor was used while AAL2 implies that two factors (e.g.
password + TOTP) have been used.
To learn more about these levels please head over to: https://www.ory.sh/kratos/docs/concepts/credentials
enum:
- aal0
- aal1
- aal2
- aal3
title: Authenticator Assurance Level (AAL)
type: string
batchPatchIdentitiesResponse:
description: Patch identities response
example:
identities:
- patch_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
identity: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
action: create
error: ""
- patch_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
identity: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
action: create
error: ""
properties:
identities:
description: The patch responses for the individual identities.
items:
$ref: '#/components/schemas/identityPatchResponse'
type: array
type: object
consistencyRequestParameters:
description: Control API consistency guarantees
properties:
consistency:
description: |-
Read Consistency Level (preview)
The read consistency level determines the consistency guarantee for reads:
strong (slow): The read is guaranteed to return the most recent data committed at the start of the read.
eventual (very fast): The result will return data that is about 4.8 seconds old.
The default consistency guarantee can be changed in the Ory Network Console or using the Ory CLI with
`ory patch project --replace '/previews/default_read_consistency_level="strong"'`.
Setting the default consistency level to `eventual` may cause regressions in the future as we add consistency
controls to more APIs. Currently, the following APIs will be affected by this setting:
`GET /admin/identities`
This feature is in preview and only available in Ory Network.
ConsistencyLevelUnset ConsistencyLevelUnset is the unset / default consistency level.
strong ConsistencyLevelStrong ConsistencyLevelStrong is the strong consistency level.
eventual ConsistencyLevelEventual ConsistencyLevelEventual is the eventual consistency level using follower read timestamps.
enum:
- ""
- strong
- eventual
type: string
x-go-enum-desc: |2-
ConsistencyLevelUnset ConsistencyLevelUnset is the unset / default consistency level.
strong ConsistencyLevelStrong ConsistencyLevelStrong is the strong consistency level.
eventual ConsistencyLevelEventual ConsistencyLevelEventual is the eventual consistency level using follower read timestamps.
type: object
continueWith:
discriminator:
mapping:
redirect_browser_to: '#/components/schemas/continueWithRedirectBrowserTo'
set_ory_session_token: '#/components/schemas/continueWithSetOrySessionToken'
show_recovery_ui: '#/components/schemas/continueWithRecoveryUi'
show_settings_ui: '#/components/schemas/continueWithSettingsUi'
show_verification_ui: '#/components/schemas/continueWithVerificationUi'
propertyName: action
oneOf:
- $ref: '#/components/schemas/continueWithVerificationUi'
- $ref: '#/components/schemas/continueWithSetOrySessionToken'
- $ref: '#/components/schemas/continueWithSettingsUi'
- $ref: '#/components/schemas/continueWithRecoveryUi'
- $ref: '#/components/schemas/continueWithRedirectBrowserTo'
type: object
continueWithRecoveryUi:
description: "Indicates, that the UI flow could be continued by showing a recovery\
\ ui"
properties:
action:
description: |-
Action will always be `show_recovery_ui`
show_recovery_ui ContinueWithActionShowRecoveryUIString
enum:
- show_recovery_ui
type: string
x-go-enum-desc: show_recovery_ui ContinueWithActionShowRecoveryUIString
flow:
$ref: '#/components/schemas/continueWithRecoveryUiFlow'
required:
- action
- flow
type: object
continueWithRecoveryUiFlow:
properties:
id:
description: The ID of the recovery flow
format: uuid
type: string
url:
description: |-
The URL of the recovery flow
If this value is set, redirect the user's browser to this URL. This value is typically unset for native clients / API flows.
type: string
required:
- id
type: object
continueWithRedirectBrowserTo:
description: "Indicates, that the UI flow could be continued by showing a recovery\
\ ui"
properties:
action:
description: |-
Action will always be `redirect_browser_to`
redirect_browser_to ContinueWithActionRedirectBrowserToString
enum:
- redirect_browser_to
type: string
x-go-enum-desc: redirect_browser_to ContinueWithActionRedirectBrowserToString
redirect_browser_to:
description: The URL to redirect the browser to
type: string
required:
- action
- redirect_browser_to
type: object
continueWithSetOrySessionToken:
description: "Indicates that a session was issued, and the application should\
\ use this token for authenticated requests"
properties:
action:
description: |-
Action will always be `set_ory_session_token`
set_ory_session_token ContinueWithActionSetOrySessionTokenString
enum:
- set_ory_session_token
type: string
x-go-enum-desc: set_ory_session_token ContinueWithActionSetOrySessionTokenString
ory_session_token:
description: Token is the token of the session
type: string
required:
- action
- ory_session_token
type: object
continueWithSettingsUi:
description: "Indicates, that the UI flow could be continued by showing a settings\
\ ui"
properties:
action:
description: |-
Action will always be `show_settings_ui`
show_settings_ui ContinueWithActionShowSettingsUIString
enum:
- show_settings_ui
type: string
x-go-enum-desc: show_settings_ui ContinueWithActionShowSettingsUIString
flow:
$ref: '#/components/schemas/continueWithSettingsUiFlow'
required:
- action
- flow
type: object
continueWithSettingsUiFlow:
properties:
id:
description: The ID of the settings flow
format: uuid
type: string
url:
description: |-
The URL of the settings flow
If this value is set, redirect the user's browser to this URL. This value is typically unset for native clients / API flows.
type: string
required:
- id
type: object
continueWithVerificationUi:
description: "Indicates, that the UI flow could be continued by showing a verification\
\ ui"
example:
action: show_verification_ui
flow:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
properties:
action:
description: |-
Action will always be `show_verification_ui`
show_verification_ui ContinueWithActionShowVerificationUIString
enum:
- show_verification_ui
type: string
x-go-enum-desc: show_verification_ui ContinueWithActionShowVerificationUIString
flow:
$ref: '#/components/schemas/continueWithVerificationUiFlow'
required:
- action
- flow
type: object
continueWithVerificationUiFlow:
example:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
properties:
id:
description: The ID of the verification flow
format: uuid
type: string
url:
description: |-
The URL of the verification flow
If this value is set, redirect the user's browser to this URL. This value is typically unset for native clients / API flows.
type: string
verifiable_address:
description: The address that should be verified in this flow
type: string
required:
- id
- verifiable_address
type: object
courierMessageStatus:
description: A Message's Status
enum:
- queued
- sent
- processing
- abandoned
type: string
courierMessageType:
description: It can either be `email` or `phone`
enum:
- email
- phone
title: A Message's Type
type: string
createFedcmFlowResponse:
description: Contains a list of all available FedCM providers.
example:
csrf_token: csrf_token
providers:
- domain_hint: domain_hint
login_hint: login_hint
config_url: config_url
fields:
- fields
- fields
nonce: nonce
parameters:
key: parameters
client_id: client_id
- domain_hint: domain_hint
login_hint: login_hint
config_url: config_url
fields:
- fields
- fields
nonce: nonce
parameters:
key: parameters
client_id: client_id
properties:
csrf_token:
type: string
providers:
items:
$ref: '#/components/schemas/Provider'
type: array
title: CreateFedcmFlowResponse
type: object
createIdentityBody:
description: Create Identity Body
properties:
credentials:
$ref: '#/components/schemas/identityWithCredentials'
external_id:
description: |-
ExternalID is an optional external ID of the identity. This is used to link
the identity to an external system. If set, the external ID must be unique
across all identities.
type: string
metadata_admin:
description: Store metadata about the user which is only accessible through
admin APIs such as `GET /admin/identities/`.
metadata_public:
description: |-
Store metadata about the identity which the identity itself can see when calling for example the
session endpoint. Do not store sensitive information (e.g. credit score) about the identity in this field.
organization_id:
format: uuid4
nullable: true
type: string
recovery_addresses:
description: |-
RecoveryAddresses contains all the addresses that can be used to recover an identity.
Use this structure to import recovery addresses for an identity. Please keep in mind
that the address needs to be represented in the Identity Schema or this field will be overwritten
on the next identity update.
items:
$ref: '#/components/schemas/recoveryIdentityAddress'
type: array
schema_id:
description: SchemaID is the ID of the JSON Schema to be used for validating
the identity's traits.
type: string
state:
description: |-
State is the identity's state.
active StateActive
inactive StateInactive
enum:
- active
- inactive
type: string
x-go-enum-desc: |-
active StateActive
inactive StateInactive
traits:
description: |-
Traits represent an identity's traits. The identity is able to create, modify, and delete traits
in a self-service manner. The input will always be validated against the JSON Schema defined
in `schema_url`.
type: object
verifiable_addresses:
description: |-
VerifiableAddresses contains all the addresses that can be verified by the user.
Use this structure to import verified addresses for an identity. Please keep in mind
that the address needs to be represented in the Identity Schema or this field will be overwritten
on the next identity update.
items:
$ref: '#/components/schemas/verifiableIdentityAddress'
type: array
required:
- schema_id
- traits
type: object
createRecoveryCodeForIdentityBody:
description: Create Recovery Code for Identity Request Body
properties:
expires_in:
description: |-
Code Expires In
The recovery code will expire after that amount of time has passed. Defaults to the configuration value of
`selfservice.methods.code.config.lifespan`.
pattern: "^([0-9]+(ns|us|ms|s|m|h))*$"
type: string
flow_type:
description: The flow type can either be `api` or `browser`.
title: Type is the flow type.
type: string
identity_id:
description: |-
Identity to Recover
The identity's ID you wish to recover.
format: uuid
type: string
required:
- identity_id
type: object
createRecoveryLinkForIdentityBody:
description: Create Recovery Link for Identity Request Body
properties:
expires_in:
description: |-
Link Expires In
The recovery link will expire after that amount of time has passed. Defaults to the configuration value of
`selfservice.methods.code.config.lifespan`.
pattern: "^[0-9]+(ns|us|ms|s|m|h)$"
type: string
identity_id:
description: |-
Identity to Recover
The identity's ID you wish to recover.
format: uuid
type: string
required:
- identity_id
type: object
deleteMySessionsCount:
description: Deleted Session Count
example:
count: 0
properties:
count:
description: The number of sessions that were revoked.
format: int64
type: integer
type: object
errorAuthenticatorAssuranceLevelNotSatisfied:
properties:
error:
$ref: '#/components/schemas/genericError'
redirect_browser_to:
description: Points to where to redirect the user to next.
type: string
title: Is returned when an active session was found but the requested AAL is
not satisfied.
type: object
errorBrowserLocationChangeRequired:
example:
error:
error:
reason: User with ID 1234 does not exist.
request: d7ef54b1-ec15-46e6-bccb-524b82c035e6
code: 404
debug: SQL field "foo" is not a bool.
details: "{}"
id: id
message: The resource could not be found
status: Not Found
redirect_browser_to: redirect_browser_to
properties:
error:
$ref: '#/components/schemas/errorGeneric'
redirect_browser_to:
description: Points to where to redirect the user to next.
type: string
title: Is sent when a flow requires a browser to change its location.
type: object
errorFlowReplaced:
description: Is sent when a flow is replaced by a different flow of the same
class
properties:
error:
$ref: '#/components/schemas/genericError'
use_flow_id:
description: The flow ID that should be used for the new flow as it contains
the correct messages.
format: uuid
type: string
type: object
errorGeneric:
description: The standard Ory JSON API error format.
example:
error:
reason: User with ID 1234 does not exist.
request: d7ef54b1-ec15-46e6-bccb-524b82c035e6
code: 404
debug: SQL field "foo" is not a bool.
details: "{}"
id: id
message: The resource could not be found
status: Not Found
properties:
error:
$ref: '#/components/schemas/genericError'
required:
- error
title: JSON API Error Response
type: object
flowError:
example:
updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
error: "{}"
properties:
created_at:
description: CreatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
error:
type: object
id:
description: ID of the error container.
format: uuid
type: string
updated_at:
description: UpdatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
required:
- id
type: object
genericError:
example:
reason: User with ID 1234 does not exist.
request: d7ef54b1-ec15-46e6-bccb-524b82c035e6
code: 404
debug: SQL field "foo" is not a bool.
details: "{}"
id: id
message: The resource could not be found
status: Not Found
properties:
code:
description: The status code
example: 404
format: int64
type: integer
debug:
description: |-
Debug information
This field is often not exposed to protect against leaking
sensitive information.
example: SQL field "foo" is not a bool.
type: string
details:
additionalProperties: false
description: Further error details
type: object
id:
description: |-
The error ID
Useful when trying to identify various errors in application logic.
type: string
message:
description: |-
Error message
The error's message.
example: The resource could not be found
type: string
reason:
description: A human-readable reason for the error
example: User with ID 1234 does not exist.
type: string
request:
description: |-
The request ID
The request ID is often exposed internally in order to trace
errors across service architectures. This is often a UUID.
example: d7ef54b1-ec15-46e6-bccb-524b82c035e6
type: string
status:
description: The status description
example: Not Found
type: string
required:
- message
type: object
healthNotReadyStatus:
properties:
errors:
additionalProperties:
type: string
description: Errors contains a list of errors that caused the not ready
status.
type: object
title: The not ready status of the service.
type: object
healthStatus:
properties:
status:
description: Status always contains "ok".
type: string
title: The health status of the service.
type: object
identity:
description: "An [identity](https://www.ory.sh/docs/kratos/concepts/identity-user-model)\
\ represents a (human) user in Ory."
example:
traits: ""
credentials:
key:
updated_at: 2000-01-23T04:56:07.000+00:00
identifiers:
- identifiers
- identifiers
created_at: 2000-01-23T04:56:07.000+00:00
type: password
config: "{}"
version: 0
state_changed_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
external_id: external_id
recovery_addresses:
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
metadata_admin: ""
updated_at: 2000-01-23T04:56:07.000+00:00
verifiable_addresses:
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
organization_id: organization_id
schema_id: schema_id
schema_url: schema_url
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: active
metadata_public: ""
properties:
created_at:
description: CreatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
credentials:
additionalProperties:
$ref: '#/components/schemas/identityCredentials'
description: Credentials represents all credentials that can be used for
authenticating this identity.
type: object
external_id:
description: |-
ExternalID is an optional external ID of the identity. This is used to link
the identity to an external system. If set, the external ID must be unique
across all identities.
type: string
id:
description: |-
ID is the identity's unique identifier.
The Identity ID can not be changed and can not be chosen. This ensures future
compatibility and optimization for distributed stores such as CockroachDB.
format: uuid
type: string
metadata_admin:
description: "NullJSONRawMessage represents a json.RawMessage that works\
\ well with JSON, SQL, and Swagger and is NULLable-"
nullable: true
metadata_public:
description: "NullJSONRawMessage represents a json.RawMessage that works\
\ well with JSON, SQL, and Swagger and is NULLable-"
nullable: true
organization_id:
format: uuid4
nullable: true
type: string
recovery_addresses:
description: RecoveryAddresses contains all the addresses that can be used
to recover an identity.
items:
$ref: '#/components/schemas/recoveryIdentityAddress'
type: array
x-omitempty: true
schema_id:
description: SchemaID is the ID of the JSON Schema to be used for validating
the identity's traits.
type: string
schema_url:
description: |-
SchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from.
format: url
type: string
state:
description: |-
State is the identity's state.
This value has currently no effect.
active StateActive
inactive StateInactive
enum:
- active
- inactive
type: string
x-go-enum-desc: |-
active StateActive
inactive StateInactive
state_changed_at:
format: date-time
title: NullTime implements sql.NullTime functionality.
type: string
traits:
description: |-
Traits represent an identity's traits. The identity is able to create, modify, and delete traits
in a self-service manner. The input will always be validated against the JSON Schema defined
in `schema_url`.
updated_at:
description: UpdatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
verifiable_addresses:
description: VerifiableAddresses contains all the addresses that can be
verified by the user.
items:
$ref: '#/components/schemas/verifiableIdentityAddress'
type: array
x-omitempty: true
required:
- id
- schema_id
- schema_url
- traits
title: Identity represents an Ory Kratos identity
type: object
identityCredentials:
description: Credentials represents a specific credential type
example:
updated_at: 2000-01-23T04:56:07.000+00:00
identifiers:
- identifiers
- identifiers
created_at: 2000-01-23T04:56:07.000+00:00
type: password
config: "{}"
version: 0
properties:
config:
title: "JSONRawMessage represents a json.RawMessage that works well with\
\ JSON, SQL, and Swagger."
type: object
created_at:
description: CreatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
identifiers:
description: Identifiers represent a list of unique identifiers this credential
type matches.
items:
type: string
type: array
type:
description: |-
Type discriminates between different types of credentials.
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
enum:
- password
- oidc
- totp
- lookup_secret
- webauthn
- code
- passkey
- profile
- saml
- link_recovery
- code_recovery
type: string
x-go-enum-desc: |-
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
updated_at:
description: UpdatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
version:
description: Version refers to the version of the credential. Useful when
changing the config schema.
format: int64
type: integer
type: object
identityCredentialsCode:
description: CredentialsCode represents a one time login/registration code
properties:
addresses:
items:
$ref: '#/components/schemas/identityCredentialsCodeAddress'
type: array
type: object
identityCredentialsCodeAddress:
properties:
address:
description: The address for this code
type: string
channel:
type: string
type: object
identityCredentialsOidc:
properties:
providers:
items:
$ref: '#/components/schemas/identityCredentialsOidcProvider'
type: array
title: CredentialsOIDC is contains the configuration for credentials of the
type oidc.
type: object
identityCredentialsOidcProvider:
properties:
initial_access_token:
type: string
initial_id_token:
type: string
initial_refresh_token:
type: string
organization:
type: string
provider:
type: string
subject:
type: string
use_auto_link:
type: boolean
title: CredentialsOIDCProvider is contains a specific OpenID COnnect credential
for a particular connection (e.g. Google).
type: object
identityCredentialsPassword:
properties:
hashed_password:
description: HashedPassword is a hash-representation of the password.
type: string
use_password_migration_hook:
description: |-
UsePasswordMigrationHook is set to true if the password should be migrated
using the password migration hook. If set, and the HashedPassword is empty, a
webhook will be called during login to migrate the password.
type: boolean
title: CredentialsPassword is contains the configuration for credentials of
the type password.
type: object
identityPatch:
description: Payload for patching an identity
properties:
create:
$ref: '#/components/schemas/createIdentityBody'
patch_id:
description: |-
The ID of this patch.
The patch ID is optional. If specified, the ID will be returned in the
response, so consumers of this API can correlate the response with the
patch.
format: uuid
type: string
type: object
identityPatchResponse:
description: Response for a single identity patch
example:
patch_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
identity: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
action: create
error: ""
properties:
action:
description: |-
The action for this specific patch
create ActionCreate Create this identity.
error ActionError Error indicates that the patch failed.
enum:
- create
- error
type: string
x-go-enum-desc: |-
create ActionCreate Create this identity.
error ActionError Error indicates that the patch failed.
error: {}
identity:
description: The identity ID payload of this patch
format: uuid
type: string
patch_id:
description: "The ID of this patch response, if an ID was specified in the\
\ patch."
format: uuid
type: string
type: object
identitySchema:
description: Raw JSON Schema
type: object
identitySchemaContainer:
description: An Identity JSON Schema Container
example:
schema: "{}"
id: id
properties:
id:
description: The ID of the Identity JSON Schema
type: string
schema:
description: The actual Identity JSON Schema
type: object
required:
- id
- schema
type: object
identitySchemas:
description: List of Identity JSON Schemas
items:
$ref: '#/components/schemas/identitySchemaContainer'
type: array
identityTraits:
description: |-
Traits represent an identity's traits. The identity is able to create, modify, and delete traits
in a self-service manner. The input will always be validated against the JSON Schema defined
in `schema_url`.
identityVerifiableAddressStatus:
description: VerifiableAddressStatus must not exceed 16 characters as that is
the limitation in the SQL Schema
type: string
identityWithCredentials:
description: Create Identity and Import Credentials
properties:
oidc:
$ref: '#/components/schemas/identityWithCredentialsOidc'
password:
$ref: '#/components/schemas/identityWithCredentialsPassword'
saml:
$ref: '#/components/schemas/identityWithCredentialsSaml'
type: object
identityWithCredentialsOidc:
description: Create Identity and Import Social Sign In Credentials
properties:
config:
$ref: '#/components/schemas/identityWithCredentialsOidcConfig'
type: object
identityWithCredentialsOidcConfig:
properties:
providers:
description: A list of OpenID Connect Providers
items:
$ref: '#/components/schemas/identityWithCredentialsOidcConfigProvider'
type: array
type: object
identityWithCredentialsOidcConfigProvider:
description: Create Identity and Import Social Sign In Credentials Configuration
properties:
organization:
format: uuid4
nullable: true
type: string
provider:
description: The OpenID Connect provider to link the subject to. Usually
something like `google` or `github`.
type: string
subject:
description: The subject (`sub`) of the OpenID Connect connection. Usually
the `sub` field of the ID Token.
type: string
use_auto_link:
description: "If set, this credential allows the user to sign in using the\
\ OpenID Connect provider without setting the subject first."
type: boolean
required:
- provider
- subject
type: object
identityWithCredentialsPassword:
description: Create Identity and Import Password Credentials
properties:
config:
$ref: '#/components/schemas/identityWithCredentialsPasswordConfig'
type: object
identityWithCredentialsPasswordConfig:
description: Create Identity and Import Password Credentials Configuration
properties:
hashed_password:
description: "The hashed password in [PHC format](https://www.ory.sh/docs/kratos/manage-identities/import-user-accounts-identities#hashed-passwords)"
type: string
password:
description: The password in plain text if no hash is available.
type: string
use_password_migration_hook:
description: "If set to true, the password will be migrated using the password\
\ migration hook."
type: boolean
type: object
identityWithCredentialsSaml:
description: Payload to import SAML credentials
properties:
config:
$ref: '#/components/schemas/identityWithCredentialsSamlConfig'
type: object
identityWithCredentialsSamlConfig:
description: Payload of SAML providers
properties:
providers:
description: A list of SAML Providers
items:
$ref: '#/components/schemas/identityWithCredentialsSamlConfigProvider'
type: array
type: object
identityWithCredentialsSamlConfigProvider:
description: Payload of specific SAML provider
properties:
organization:
format: uuid4
nullable: true
type: string
provider:
description: The SAML provider to link the subject to.
type: string
subject:
description: The unique subject of the SAML connection. This value must
be immutable at the source.
type: string
required:
- provider
- subject
type: object
jsonPatch:
description: A JSONPatch document as defined by RFC 6902
properties:
from:
description: |-
This field is used together with operation "move" and uses JSON Pointer notation.
Learn more [about JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901#section-5).
example: /name
type: string
op:
description: "The operation to be performed. One of \"add\", \"remove\"\
, \"replace\", \"move\", \"copy\", or \"test\"."
example: replace
type: string
path:
description: |-
The path to the target path. Uses JSON pointer notation.
Learn more [about JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901#section-5).
example: /name
type: string
value:
description: |-
The value to be used within the operations.
Learn more [about JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901#section-5).
example: foobar
required:
- op
- path
type: object
jsonPatchDocument:
description: A JSONPatchDocument request
items:
$ref: '#/components/schemas/jsonPatch'
type: array
loginFlow:
description: |-
This object represents a login flow. A login flow is initiated at the "Initiate Login API / Browser Flow"
endpoint by a client.
Once a login flow is completed successfully, a session cookie or session token will be issued.
example:
identity_schema: identity_schema
requested_aal: aal0
active: password
created_at: 2000-01-23T04:56:07.000+00:00
refresh: true
return_to: return_to
session_token_exchange_code: session_token_exchange_code
type: type
issued_at: 2000-01-23T04:56:07.000+00:00
request_url: request_url
expires_at: 2000-01-23T04:56:07.000+00:00
oauth2_login_request:
requested_access_token_audience:
- requested_access_token_audience
- requested_access_token_audience
subject: subject
oidc_context:
login_hint: login_hint
ui_locales:
- ui_locales
- ui_locales
id_token_hint_claims:
key: ""
acr_values:
- acr_values
- acr_values
display: display
challenge: challenge
client:
metadata: ""
token_endpoint_auth_signing_alg: token_endpoint_auth_signing_alg
client_uri: client_uri
jwt_bearer_grant_access_token_lifespan: jwt_bearer_grant_access_token_lifespan
jwks: ""
logo_uri: logo_uri
created_at: 2000-01-23T04:56:07.000+00:00
registration_client_uri: registration_client_uri
allowed_cors_origins:
- allowed_cors_origins
- allowed_cors_origins
refresh_token_grant_access_token_lifespan: refresh_token_grant_access_token_lifespan
registration_access_token: registration_access_token
client_id: client_id
token_endpoint_auth_method: token_endpoint_auth_method
userinfo_signed_response_alg: userinfo_signed_response_alg
authorization_code_grant_id_token_lifespan: authorization_code_grant_id_token_lifespan
authorization_code_grant_refresh_token_lifespan: authorization_code_grant_refresh_token_lifespan
client_credentials_grant_access_token_lifespan: client_credentials_grant_access_token_lifespan
updated_at: 2000-01-23T04:56:07.000+00:00
scope: scope
request_uris:
- request_uris
- request_uris
client_secret: client_secret
backchannel_logout_session_required: true
backchannel_logout_uri: backchannel_logout_uri
client_name: client_name
policy_uri: policy_uri
owner: owner
skip_consent: true
audience:
- audience
- audience
authorization_code_grant_access_token_lifespan: authorization_code_grant_access_token_lifespan
post_logout_redirect_uris:
- post_logout_redirect_uris
- post_logout_redirect_uris
grant_types:
- grant_types
- grant_types
subject_type: subject_type
refresh_token_grant_refresh_token_lifespan: refresh_token_grant_refresh_token_lifespan
redirect_uris:
- redirect_uris
- redirect_uris
sector_identifier_uri: sector_identifier_uri
frontchannel_logout_session_required: true
frontchannel_logout_uri: frontchannel_logout_uri
skip_logout_consent: true
refresh_token_grant_id_token_lifespan: refresh_token_grant_id_token_lifespan
implicit_grant_id_token_lifespan: implicit_grant_id_token_lifespan
client_secret_expires_at: 0
implicit_grant_access_token_lifespan: implicit_grant_access_token_lifespan
access_token_strategy: access_token_strategy
jwks_uri: jwks_uri
request_object_signing_alg: request_object_signing_alg
tos_uri: tos_uri
contacts:
- contacts
- contacts
response_types:
- response_types
- response_types
session_id: session_id
skip: true
request_url: request_url
requested_scope:
- requested_scope
- requested_scope
transient_payload: "{}"
ui:
nodes:
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
method: method
action: action
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
updated_at: 2000-01-23T04:56:07.000+00:00
oauth2_login_challenge: oauth2_login_challenge
organization_id: organization_id
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: ""
properties:
active:
description: |-
The active login method
If set contains the login method used. If the flow is new, it is unset.
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
enum:
- password
- oidc
- totp
- lookup_secret
- webauthn
- code
- passkey
- profile
- saml
- link_recovery
- code_recovery
type: string
x-go-enum-desc: |-
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
created_at:
description: CreatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
expires_at:
description: |-
ExpiresAt is the time (UTC) when the flow expires. If the user still wishes to log in,
a new flow has to be initiated.
format: date-time
type: string
id:
description: |-
ID represents the flow's unique ID. When performing the login flow, this
represents the id in the login UI's query parameter: http:///?flow=
format: uuid
type: string
identity_schema:
description: |-
IdentitySchema optionally holds the ID of the identity schema that is used
for this flow. This value can be set by the user when creating the flow and
should be retained when the flow is saved or converted to another flow.
type: string
issued_at:
description: IssuedAt is the time (UTC) when the flow started.
format: date-time
type: string
oauth2_login_challenge:
description: |-
Ory OAuth 2.0 Login Challenge.
This value is set using the `login_challenge` query parameter of the registration and login endpoints.
If set will cooperate with Ory OAuth2 and OpenID to act as an OAuth2 server / OpenID Provider.
type: string
oauth2_login_request:
$ref: '#/components/schemas/OAuth2LoginRequest'
organization_id:
format: uuid4
nullable: true
type: string
refresh:
description: Refresh stores whether this login flow should enforce re-authentication.
type: boolean
request_url:
description: |-
RequestURL is the initial URL that was requested from Ory Kratos. It can be used
to forward information contained in the URL's path or query for example.
type: string
requested_aal:
$ref: '#/components/schemas/authenticatorAssuranceLevel'
return_to:
description: ReturnTo contains the requested return_to URL.
type: string
session_token_exchange_code:
description: |-
SessionTokenExchangeCode holds the secret code that the client can use to retrieve a session token after the login flow has been completed.
This is only set if the client has requested a session token exchange code, and if the flow is of type "api",
and only on creating the login flow.
type: string
state:
description: |-
State represents the state of this request:
choose_method: ask the user to choose a method to sign in with
sent_email: the email has been sent to the user
passed_challenge: the request was successful and the login challenge was passed.
transient_payload:
description: TransientPayload is used to pass data from the login to hooks
and email templates
type: object
type:
description: The flow type can either be `api` or `browser`.
title: Type is the flow type.
type: string
ui:
$ref: '#/components/schemas/uiContainer'
updated_at:
description: UpdatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
required:
- expires_at
- id
- issued_at
- request_url
- state
- type
- ui
title: Login Flow
type: object
loginFlowState:
description: The experimental state represents the state of a login flow. This
field is EXPERIMENTAL and subject to change!
enum:
- choose_method
- sent_email
- passed_challenge
title: Login flow state (experimental)
type: string
logoutFlow:
description: Logout Flow
example:
logout_url: logout_url
logout_token: logout_token
properties:
logout_token:
description: LogoutToken can be used to perform logout using AJAX.
type: string
logout_url:
description: |-
LogoutURL can be opened in a browser to sign the user out.
format: uri
type: string
required:
- logout_token
- logout_url
type: object
message:
example:
dispatches:
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
message_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
error: "{}"
status: failed
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
message_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
error: "{}"
status: failed
updated_at: 2000-01-23T04:56:07.000+00:00
subject: subject
channel: channel
recipient: recipient
created_at: 2000-01-23T04:56:07.000+00:00
send_count: 0
template_type: recovery_invalid
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
body: body
type: email
status: queued
properties:
body:
type: string
channel:
type: string
created_at:
description: CreatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
dispatches:
description: |-
Dispatches store information about the attempts of delivering a message
May contain an error if any happened, or just the `success` state.
items:
$ref: '#/components/schemas/messageDispatch'
type: array
id:
format: uuid
type: string
recipient:
type: string
send_count:
format: int64
type: integer
status:
$ref: '#/components/schemas/courierMessageStatus'
subject:
type: string
template_type:
description: |2-
recovery_invalid TypeRecoveryInvalid
recovery_valid TypeRecoveryValid
recovery_code_invalid TypeRecoveryCodeInvalid
recovery_code_valid TypeRecoveryCodeValid
verification_invalid TypeVerificationInvalid
verification_valid TypeVerificationValid
verification_code_invalid TypeVerificationCodeInvalid
verification_code_valid TypeVerificationCodeValid
stub TypeTestStub
login_code_valid TypeLoginCodeValid
registration_code_valid TypeRegistrationCodeValid
enum:
- recovery_invalid
- recovery_valid
- recovery_code_invalid
- recovery_code_valid
- verification_invalid
- verification_valid
- verification_code_invalid
- verification_code_valid
- stub
- login_code_valid
- registration_code_valid
type: string
x-go-enum-desc: |-
recovery_invalid TypeRecoveryInvalid
recovery_valid TypeRecoveryValid
recovery_code_invalid TypeRecoveryCodeInvalid
recovery_code_valid TypeRecoveryCodeValid
verification_invalid TypeVerificationInvalid
verification_valid TypeVerificationValid
verification_code_invalid TypeVerificationCodeInvalid
verification_code_valid TypeVerificationCodeValid
stub TypeTestStub
login_code_valid TypeLoginCodeValid
registration_code_valid TypeRegistrationCodeValid
type:
$ref: '#/components/schemas/courierMessageType'
updated_at:
description: UpdatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
required:
- body
- created_at
- id
- recipient
- send_count
- status
- subject
- template_type
- type
- updated_at
type: object
messageDispatch:
description: |-
MessageDispatch represents an attempt of sending a courier message
It contains the status of the attempt (failed or successful) and the error if any occured
example:
updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
message_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
error: "{}"
status: failed
properties:
created_at:
description: CreatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
error:
title: "JSONRawMessage represents a json.RawMessage that works well with\
\ JSON, SQL, and Swagger."
type: object
id:
description: The ID of this message dispatch
format: uuid
type: string
message_id:
description: The ID of the message being dispatched
format: uuid
type: string
status:
description: |-
The status of this dispatch
Either "failed" or "success"
failed CourierMessageDispatchStatusFailed
success CourierMessageDispatchStatusSuccess
enum:
- failed
- success
type: string
x-go-enum-desc: |-
failed CourierMessageDispatchStatusFailed
success CourierMessageDispatchStatusSuccess
updated_at:
description: UpdatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
required:
- created_at
- id
- message_id
- status
- updated_at
type: object
needsPrivilegedSessionError:
properties:
error:
$ref: '#/components/schemas/genericError'
redirect_browser_to:
description: Points to where to redirect the user to next.
type: string
required:
- redirect_browser_to
title: Is sent when a privileged session is required to perform the settings
update.
type: object
nullDuration:
nullable: true
pattern: "^[0-9]+(ns|us|ms|s|m|h)$"
type: string
nullInt64:
nullable: true
type: integer
nullJsonRawMessage:
description: "NullJSONRawMessage represents a json.RawMessage that works well\
\ with JSON, SQL, and Swagger and is NULLable-"
nullable: true
nullTime:
format: date-time
title: NullTime implements sql.NullTime functionality.
type: string
patchIdentitiesBody:
description: Patch Identities Body
properties:
identities:
description: |-
Identities holds the list of patches to apply
required
items:
$ref: '#/components/schemas/identityPatch'
type: array
type: object
performNativeLogoutBody:
description: Perform Native Logout Request Body
properties:
session_token:
description: |-
The Session Token
Invalidate this session token.
type: string
required:
- session_token
type: object
recoveryCodeForIdentity:
description: Used when an administrator creates a recovery code for an identity.
example:
expires_at: 2000-01-23T04:56:07.000+00:00
recovery_code: recovery_code
recovery_link: recovery_link
properties:
expires_at:
description: |-
Expires At is the timestamp of when the recovery flow expires
The timestamp when the recovery code expires.
format: date-time
type: string
recovery_code:
description: RecoveryCode is the code that can be used to recover the account
type: string
recovery_link:
description: |-
RecoveryLink with flow
This link opens the recovery UI with an empty `code` field.
type: string
required:
- recovery_code
- recovery_link
title: Recovery Code for Identity
type: object
recoveryFlow:
description: |-
This request is used when an identity wants to recover their account.
We recommend reading the [Account Recovery Documentation](../self-service/flows/password-reset-account-recovery)
example:
expires_at: 2000-01-23T04:56:07.000+00:00
transient_payload: "{}"
ui:
nodes:
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
method: method
action: action
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
continue_with:
- action: show_verification_ui
flow:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
- action: show_verification_ui
flow:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
active: active
return_to: return_to
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: ""
type: type
issued_at: 2000-01-23T04:56:07.000+00:00
request_url: request_url
properties:
active:
description: |-
Active, if set, contains the recovery method that is being used. It is initially
not set.
type: string
continue_with:
description: Contains possible actions that could follow this flow
items:
$ref: '#/components/schemas/continueWith'
type: array
expires_at:
description: |-
ExpiresAt is the time (UTC) when the request expires. If the user still wishes to update the setting,
a new request has to be initiated.
format: date-time
type: string
id:
description: |-
ID represents the request's unique ID. When performing the recovery flow, this
represents the id in the recovery ui's query parameter: http://?request=
format: uuid
type: string
issued_at:
description: IssuedAt is the time (UTC) when the request occurred.
format: date-time
type: string
request_url:
description: |-
RequestURL is the initial URL that was requested from Ory Kratos. It can be used
to forward information contained in the URL's path or query for example.
type: string
return_to:
description: ReturnTo contains the requested return_to URL.
type: string
state:
description: |-
State represents the state of this request:
choose_method: ask the user to choose a method (e.g. recover account via email)
sent_email: the email has been sent to the user
passed_challenge: the request was successful and the recovery challenge was passed.
transient_payload:
description: TransientPayload is used to pass data from the recovery flow
to hooks and email templates
type: object
type:
description: The flow type can either be `api` or `browser`.
title: Type is the flow type.
type: string
ui:
$ref: '#/components/schemas/uiContainer'
required:
- expires_at
- id
- issued_at
- request_url
- state
- type
- ui
title: A Recovery Flow
type: object
recoveryFlowState:
description: The experimental state represents the state of a recovery flow.
This field is EXPERIMENTAL and subject to change!
enum:
- choose_method
- sent_email
- passed_challenge
title: Recovery flow state (experimental)
type: string
recoveryIdentityAddress:
example:
updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
properties:
created_at:
description: CreatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
id:
format: uuid
type: string
updated_at:
description: UpdatedAt is a helper struct field for gobuffalo.pop.
format: date-time
type: string
value:
type: string
via:
type: string
required:
- value
- via
type: object
recoveryLinkForIdentity:
description: Used when an administrator creates a recovery link for an identity.
example:
expires_at: 2000-01-23T04:56:07.000+00:00
recovery_link: recovery_link
properties:
expires_at:
description: |-
Recovery Link Expires At
The timestamp when the recovery link expires.
format: date-time
type: string
recovery_link:
description: |-
Recovery Link
This link can be used to recover the account.
type: string
required:
- recovery_link
title: Identity Recovery Link
type: object
registrationFlow:
example:
identity_schema: identity_schema
active: password
return_to: return_to
session_token_exchange_code: session_token_exchange_code
type: type
issued_at: 2000-01-23T04:56:07.000+00:00
request_url: request_url
expires_at: 2000-01-23T04:56:07.000+00:00
oauth2_login_request:
requested_access_token_audience:
- requested_access_token_audience
- requested_access_token_audience
subject: subject
oidc_context:
login_hint: login_hint
ui_locales:
- ui_locales
- ui_locales
id_token_hint_claims:
key: ""
acr_values:
- acr_values
- acr_values
display: display
challenge: challenge
client:
metadata: ""
token_endpoint_auth_signing_alg: token_endpoint_auth_signing_alg
client_uri: client_uri
jwt_bearer_grant_access_token_lifespan: jwt_bearer_grant_access_token_lifespan
jwks: ""
logo_uri: logo_uri
created_at: 2000-01-23T04:56:07.000+00:00
registration_client_uri: registration_client_uri
allowed_cors_origins:
- allowed_cors_origins
- allowed_cors_origins
refresh_token_grant_access_token_lifespan: refresh_token_grant_access_token_lifespan
registration_access_token: registration_access_token
client_id: client_id
token_endpoint_auth_method: token_endpoint_auth_method
userinfo_signed_response_alg: userinfo_signed_response_alg
authorization_code_grant_id_token_lifespan: authorization_code_grant_id_token_lifespan
authorization_code_grant_refresh_token_lifespan: authorization_code_grant_refresh_token_lifespan
client_credentials_grant_access_token_lifespan: client_credentials_grant_access_token_lifespan
updated_at: 2000-01-23T04:56:07.000+00:00
scope: scope
request_uris:
- request_uris
- request_uris
client_secret: client_secret
backchannel_logout_session_required: true
backchannel_logout_uri: backchannel_logout_uri
client_name: client_name
policy_uri: policy_uri
owner: owner
skip_consent: true
audience:
- audience
- audience
authorization_code_grant_access_token_lifespan: authorization_code_grant_access_token_lifespan
post_logout_redirect_uris:
- post_logout_redirect_uris
- post_logout_redirect_uris
grant_types:
- grant_types
- grant_types
subject_type: subject_type
refresh_token_grant_refresh_token_lifespan: refresh_token_grant_refresh_token_lifespan
redirect_uris:
- redirect_uris
- redirect_uris
sector_identifier_uri: sector_identifier_uri
frontchannel_logout_session_required: true
frontchannel_logout_uri: frontchannel_logout_uri
skip_logout_consent: true
refresh_token_grant_id_token_lifespan: refresh_token_grant_id_token_lifespan
implicit_grant_id_token_lifespan: implicit_grant_id_token_lifespan
client_secret_expires_at: 0
implicit_grant_access_token_lifespan: implicit_grant_access_token_lifespan
access_token_strategy: access_token_strategy
jwks_uri: jwks_uri
request_object_signing_alg: request_object_signing_alg
tos_uri: tos_uri
contacts:
- contacts
- contacts
response_types:
- response_types
- response_types
session_id: session_id
skip: true
request_url: request_url
requested_scope:
- requested_scope
- requested_scope
transient_payload: "{}"
ui:
nodes:
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
method: method
action: action
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
oauth2_login_challenge: oauth2_login_challenge
organization_id: organization_id
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: ""
properties:
active:
description: |-
Active, if set, contains the registration method that is being used. It is initially
not set.
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
enum:
- password
- oidc
- totp
- lookup_secret
- webauthn
- code
- passkey
- profile
- saml
- link_recovery
- code_recovery
type: string
x-go-enum-desc: |-
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
expires_at:
description: |-
ExpiresAt is the time (UTC) when the flow expires. If the user still wishes to log in,
a new flow has to be initiated.
format: date-time
type: string
id:
description: |-
ID represents the flow's unique ID. When performing the registration flow, this
represents the id in the registration ui's query parameter: http:///?flow=
format: uuid
type: string
identity_schema:
description: |-
IdentitySchema optionally holds the ID of the identity schema that is used
for this flow. This value can be set by the user when creating the flow and
should be retained when the flow is saved or converted to another flow.
type: string
issued_at:
description: IssuedAt is the time (UTC) when the flow occurred.
format: date-time
type: string
oauth2_login_challenge:
description: |-
Ory OAuth 2.0 Login Challenge.
This value is set using the `login_challenge` query parameter of the registration and login endpoints.
If set will cooperate with Ory OAuth2 and OpenID to act as an OAuth2 server / OpenID Provider.
type: string
oauth2_login_request:
$ref: '#/components/schemas/OAuth2LoginRequest'
organization_id:
format: uuid4
nullable: true
type: string
request_url:
description: |-
RequestURL is the initial URL that was requested from Ory Kratos. It can be used
to forward information contained in the URL's path or query for example.
type: string
return_to:
description: ReturnTo contains the requested return_to URL.
type: string
session_token_exchange_code:
description: |-
SessionTokenExchangeCode holds the secret code that the client can use to retrieve a session token after the flow has been completed.
This is only set if the client has requested a session token exchange code, and if the flow is of type "api",
and only on creating the flow.
type: string
state:
description: |-
State represents the state of this request:
choose_method: ask the user to choose a method (e.g. registration with email)
sent_email: the email has been sent to the user
passed_challenge: the request was successful and the registration challenge was passed.
transient_payload:
description: TransientPayload is used to pass data from the registration
to a webhook
type: object
type:
description: The flow type can either be `api` or `browser`.
title: Type is the flow type.
type: string
ui:
$ref: '#/components/schemas/uiContainer'
required:
- expires_at
- id
- issued_at
- request_url
- state
- type
- ui
type: object
registrationFlowState:
description: The experimental state represents the state of a registration flow.
This field is EXPERIMENTAL and subject to change!
enum:
- choose_method
- sent_email
- passed_challenge
title: Registration flow state (experimental)
type: string
selfServiceFlowExpiredError:
description: Is sent when a flow is expired
properties:
error:
$ref: '#/components/schemas/genericError'
expired_at:
description: When the flow has expired
format: date-time
type: string
since:
description: |-
A Duration represents the elapsed time between two instants
as an int64 nanosecond count. The representation limits the
largest representable duration to approximately 290 years.
format: int64
type: integer
use_flow_id:
description: The flow ID that should be used for the new flow as it contains
the correct messages.
format: uuid
type: string
type: object
selfServiceFlowType:
description: The flow type can either be `api` or `browser`.
title: Type is the flow type.
type: string
session:
description: A Session
example:
tokenized: tokenized
expires_at: 2000-01-23T04:56:07.000+00:00
devices:
- location: location
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
ip_address: ip_address
user_agent: user_agent
- location: location
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
ip_address: ip_address
user_agent: user_agent
authentication_methods:
- completed_at: 2000-01-23T04:56:07.000+00:00
method: password
provider: provider
organization: organization
aal: aal0
- completed_at: 2000-01-23T04:56:07.000+00:00
method: password
provider: provider
organization: organization
aal: aal0
authenticator_assurance_level: null
identity:
traits: ""
credentials:
key:
updated_at: 2000-01-23T04:56:07.000+00:00
identifiers:
- identifiers
- identifiers
created_at: 2000-01-23T04:56:07.000+00:00
type: password
config: "{}"
version: 0
state_changed_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
external_id: external_id
recovery_addresses:
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
metadata_admin: ""
updated_at: 2000-01-23T04:56:07.000+00:00
verifiable_addresses:
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
organization_id: organization_id
schema_id: schema_id
schema_url: schema_url
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: active
metadata_public: ""
authenticated_at: 2000-01-23T04:56:07.000+00:00
active: true
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
issued_at: 2000-01-23T04:56:07.000+00:00
properties:
active:
description: Active state. If false the session is no longer active.
type: boolean
authenticated_at:
description: |-
The Session Authentication Timestamp
When this session was authenticated at. If multi-factor authentication was used this
is the time when the last factor was authenticated (e.g. the TOTP code challenge was completed).
format: date-time
type: string
authentication_methods:
description: A list of authenticators which were used to authenticate the
session.
items:
$ref: '#/components/schemas/sessionAuthenticationMethod'
title: List of (Used) AuthenticationMethods
type: array
authenticator_assurance_level:
$ref: '#/components/schemas/authenticatorAssuranceLevel'
devices:
description: Devices has history of all endpoints where the session was
used
items:
$ref: '#/components/schemas/sessionDevice'
type: array
expires_at:
description: |-
The Session Expiry
When this session expires at.
format: date-time
type: string
id:
description: Session ID
format: uuid
type: string
identity:
$ref: '#/components/schemas/identity'
issued_at:
description: |-
The Session Issuance Timestamp
When this session was issued at. Usually equal or close to `authenticated_at`.
format: date-time
type: string
tokenized:
description: |-
Tokenized is the tokenized (e.g. JWT) version of the session.
It is only set when the `tokenize_as` query parameter was set to a valid tokenize template during calls to `/session/whoami`.
type: string
required:
- id
type: object
sessionAuthenticationMethod:
description: A singular authenticator used during authentication / login.
example:
completed_at: 2000-01-23T04:56:07.000+00:00
method: password
provider: provider
organization: organization
aal: aal0
properties:
aal:
$ref: '#/components/schemas/authenticatorAssuranceLevel'
completed_at:
description: When the authentication challenge was completed.
format: date-time
type: string
method:
description: |-
The method used in this authenticator.
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
enum:
- password
- oidc
- totp
- lookup_secret
- webauthn
- code
- passkey
- profile
- saml
- link_recovery
- code_recovery
type: string
x-go-enum-desc: |-
password CredentialsTypePassword
oidc CredentialsTypeOIDC
totp CredentialsTypeTOTP
lookup_secret CredentialsTypeLookup
webauthn CredentialsTypeWebAuthn
code CredentialsTypeCodeAuth
passkey CredentialsTypePasskey
profile CredentialsTypeProfile
saml CredentialsTypeSAML
link_recovery CredentialsTypeRecoveryLink CredentialsTypeRecoveryLink is a special credential type linked to the link strategy (recovery flow). It is not used within the credentials object itself.
code_recovery CredentialsTypeRecoveryCode
organization:
description: The Organization id used for authentication
type: string
provider:
description: OIDC or SAML provider id used for authentication
type: string
title: AuthenticationMethod identifies an authentication method
type: object
sessionAuthenticationMethods:
description: A list of authenticators which were used to authenticate the session.
items:
$ref: '#/components/schemas/sessionAuthenticationMethod'
title: List of (Used) AuthenticationMethods
type: array
sessionDevice:
description: Device corresponding to a Session
example:
location: location
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
ip_address: ip_address
user_agent: user_agent
properties:
id:
description: Device record ID
format: uuid
type: string
ip_address:
description: IPAddress of the client
type: string
location:
description: Geo Location corresponding to the IP Address
type: string
user_agent:
description: UserAgent of the client
type: string
required:
- id
type: object
settingsFlow:
description: |-
This flow is used when an identity wants to update settings
(e.g. profile data, passwords, ...) in a selfservice manner.
We recommend reading the [User Settings Documentation](../self-service/flows/user-settings)
example:
expires_at: 2000-01-23T04:56:07.000+00:00
transient_payload: "{}"
ui:
nodes:
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
method: method
action: action
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
identity:
traits: ""
credentials:
key:
updated_at: 2000-01-23T04:56:07.000+00:00
identifiers:
- identifiers
- identifiers
created_at: 2000-01-23T04:56:07.000+00:00
type: password
config: "{}"
version: 0
state_changed_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
external_id: external_id
recovery_addresses:
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
metadata_admin: ""
updated_at: 2000-01-23T04:56:07.000+00:00
verifiable_addresses:
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
organization_id: organization_id
schema_id: schema_id
schema_url: schema_url
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: active
metadata_public: ""
continue_with:
- action: show_verification_ui
flow:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
- action: show_verification_ui
flow:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
active: active
return_to: return_to
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: ""
type: type
issued_at: 2000-01-23T04:56:07.000+00:00
request_url: request_url
properties:
active:
description: |-
Active, if set, contains the registration method that is being used. It is initially
not set.
type: string
continue_with:
description: |-
Contains a list of actions, that could follow this flow
It can, for example, contain a reference to the verification flow, created as part of the user's
registration.
items:
$ref: '#/components/schemas/continueWith'
type: array
expires_at:
description: |-
ExpiresAt is the time (UTC) when the flow expires. If the user still wishes to update the setting,
a new flow has to be initiated.
format: date-time
type: string
id:
description: |-
ID represents the flow's unique ID. When performing the settings flow, this
represents the id in the settings ui's query parameter: http://?flow=
format: uuid
type: string
identity:
$ref: '#/components/schemas/identity'
issued_at:
description: IssuedAt is the time (UTC) when the flow occurred.
format: date-time
type: string
request_url:
description: |-
RequestURL is the initial URL that was requested from Ory Kratos. It can be used
to forward information contained in the URL's path or query for example.
type: string
return_to:
description: ReturnTo contains the requested return_to URL.
type: string
state:
description: |-
State represents the state of this flow. It knows two states:
show_form: No user data has been collected, or it is invalid, and thus the form should be shown.
success: Indicates that the settings flow has been updated successfully with the provided data.
Done will stay true when repeatedly checking. If set to true, done will revert back to false only
when a flow with invalid (e.g. "please use a valid phone number") data was sent.
transient_payload:
description: TransientPayload is used to pass data from the settings flow
to hooks and email templates
type: object
type:
description: The flow type can either be `api` or `browser`.
title: Type is the flow type.
type: string
ui:
$ref: '#/components/schemas/uiContainer'
required:
- expires_at
- id
- identity
- issued_at
- request_url
- state
- type
- ui
title: Flow represents a Settings Flow
type: object
settingsFlowState:
description: The experimental state represents the state of a settings flow.
This field is EXPERIMENTAL and subject to change!
enum:
- show_form
- success
title: Settings flow state (experimental)
type: string
successfulCodeExchangeResponse:
description: The Response for Registration Flows via API
properties:
session:
$ref: '#/components/schemas/session'
session_token:
description: |-
The Session Token
A session token is equivalent to a session cookie, but it can be sent in the HTTP Authorization
Header:
Authorization: bearer ${session-token}
The session token is only issued for API flows, not for Browser flows!
type: string
required:
- session
type: object
successfulNativeLogin:
description: The Response for Login Flows via API
example:
session_token: session_token
session:
tokenized: tokenized
expires_at: 2000-01-23T04:56:07.000+00:00
devices:
- location: location
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
ip_address: ip_address
user_agent: user_agent
- location: location
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
ip_address: ip_address
user_agent: user_agent
authentication_methods:
- completed_at: 2000-01-23T04:56:07.000+00:00
method: password
provider: provider
organization: organization
aal: aal0
- completed_at: 2000-01-23T04:56:07.000+00:00
method: password
provider: provider
organization: organization
aal: aal0
authenticator_assurance_level: null
identity:
traits: ""
credentials:
key:
updated_at: 2000-01-23T04:56:07.000+00:00
identifiers:
- identifiers
- identifiers
created_at: 2000-01-23T04:56:07.000+00:00
type: password
config: "{}"
version: 0
state_changed_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
external_id: external_id
recovery_addresses:
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
metadata_admin: ""
updated_at: 2000-01-23T04:56:07.000+00:00
verifiable_addresses:
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
organization_id: organization_id
schema_id: schema_id
schema_url: schema_url
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: active
metadata_public: ""
authenticated_at: 2000-01-23T04:56:07.000+00:00
active: true
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
issued_at: 2000-01-23T04:56:07.000+00:00
continue_with:
- action: show_verification_ui
flow:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
- action: show_verification_ui
flow:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
properties:
continue_with:
description: |-
Contains a list of actions, that could follow this flow
It can, for example, this will contain a reference to the verification flow, created as part of the user's
registration or the token of the session.
items:
$ref: '#/components/schemas/continueWith'
type: array
session:
$ref: '#/components/schemas/session'
session_token:
description: |-
The Session Token
A session token is equivalent to a session cookie, but it can be sent in the HTTP Authorization
Header:
Authorization: bearer ${session-token}
The session token is only issued for API flows, not for Browser flows!
type: string
required:
- session
type: object
successfulNativeRegistration:
description: The Response for Registration Flows via API
example:
session_token: session_token
identity:
traits: ""
credentials:
key:
updated_at: 2000-01-23T04:56:07.000+00:00
identifiers:
- identifiers
- identifiers
created_at: 2000-01-23T04:56:07.000+00:00
type: password
config: "{}"
version: 0
state_changed_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
external_id: external_id
recovery_addresses:
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
metadata_admin: ""
updated_at: 2000-01-23T04:56:07.000+00:00
verifiable_addresses:
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
organization_id: organization_id
schema_id: schema_id
schema_url: schema_url
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: active
metadata_public: ""
session:
tokenized: tokenized
expires_at: 2000-01-23T04:56:07.000+00:00
devices:
- location: location
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
ip_address: ip_address
user_agent: user_agent
- location: location
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
ip_address: ip_address
user_agent: user_agent
authentication_methods:
- completed_at: 2000-01-23T04:56:07.000+00:00
method: password
provider: provider
organization: organization
aal: aal0
- completed_at: 2000-01-23T04:56:07.000+00:00
method: password
provider: provider
organization: organization
aal: aal0
authenticator_assurance_level: null
identity:
traits: ""
credentials:
key:
updated_at: 2000-01-23T04:56:07.000+00:00
identifiers:
- identifiers
- identifiers
created_at: 2000-01-23T04:56:07.000+00:00
type: password
config: "{}"
version: 0
state_changed_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
external_id: external_id
recovery_addresses:
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
- updated_at: 2000-01-23T04:56:07.000+00:00
created_at: 2000-01-23T04:56:07.000+00:00
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
via: via
metadata_admin: ""
updated_at: 2000-01-23T04:56:07.000+00:00
verifiable_addresses:
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
- updated_at: 2014-01-01T23:28:56.782Z
verified_at: 2000-01-23T04:56:07.000+00:00
verified: true
created_at: 2014-01-01T23:28:56.782Z
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
value: value
status: status
via: email
organization_id: organization_id
schema_id: schema_id
schema_url: schema_url
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
state: active
metadata_public: ""
authenticated_at: 2000-01-23T04:56:07.000+00:00
active: true
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
issued_at: 2000-01-23T04:56:07.000+00:00
continue_with:
- action: show_verification_ui
flow:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
- action: show_verification_ui
flow:
verifiable_address: verifiable_address
id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
url: url
properties:
continue_with:
description: |-
Contains a list of actions, that could follow this flow
It can, for example, this will contain a reference to the verification flow, created as part of the user's
registration or the token of the session.
items:
$ref: '#/components/schemas/continueWith'
type: array
identity:
$ref: '#/components/schemas/identity'
session:
$ref: '#/components/schemas/session'
session_token:
description: |-
The Session Token
This field is only set when the session hook is configured as a post-registration hook.
A session token is equivalent to a session cookie, but it can be sent in the HTTP Authorization
Header:
Authorization: bearer ${session-token}
The session token is only issued for API flows, not for Browser flows!
type: string
required:
- identity
type: object
tokenPagination:
properties:
page_size:
default: 250
description: |-
Items per page
This is the number of items per page to return.
For details on pagination please head over to the [pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
format: int64
maximum: 1000
minimum: 1
type: integer
page_token:
description: |-
Next Page Token
The next page token.
For details on pagination please head over to the [pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
type: string
type: object
tokenPaginationHeaders:
properties:
link:
description: |-
The link header contains pagination links.
For details on pagination please head over to the [pagination documentation](https://www.ory.sh/docs/ecosystem/api-design#pagination).
in: header
type: string
x-total-count:
description: |-
The total number of clients.
in: header
type: string
type: object
uiContainer:
description: Container represents a HTML Form. The container can work with both
HTTP Form and JSON requests
example:
nodes:
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
- meta:
label:
context: "{}"
id: 6
text: text
type: info
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
attributes:
autocomplete: email
maxlength: 1
onclick: onclick
pattern: pattern
onclickTrigger: oryWebAuthnRegistration
label:
context: "{}"
id: 6
text: text
type: info
type: text
required: true
onload: onload
node_type: input
onloadTrigger: oryWebAuthnRegistration
name: name
disabled: true
value: ""
type: text
group: default
method: method
action: action
messages:
- context: "{}"
id: 6
text: text
type: info
- context: "{}"
id: 6
text: text
type: info
properties:
action:
description: "Action should be used as the form action URL `