Identity management

The Identity endpoints allow you to manage user identities, including creating, reading, updating, and deleting identities, as well as managing their credentials and sessions.

Create an identity

curl -X POST https://{project}.projects.oryapis.com/admin/identities \
  -H "Authorization: Bearer ory_at_..." \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "default",
    "traits": {
      "email": "[email protected]",
      "name": "John Doe"
    }
  }'

Create an identity with optional credentials, metadata, and recovery addresses.

Request body

schema_id

string

required

The ID of the JSON Schema to validate the identity’s traits.

traits

object

required

Identity traits validated against the schema. Typically includes email, name, username, etc.

credentials

object

Import credentials for the identity.

Show credentials properties

password.config.password

string

Plaintext password (will be hashed).

password.config.hashed_password

string

Pre-hashed password in PHC format.

oidc.config.providers

array

Array of OIDC provider configurations.

Show provider properties

provider

string

required

Provider ID (e.g., “google”, “github”).

subject

string

required

The subject (sub) from the ID Token.

state

string

Identity state: active or inactive.

metadata_public

object

Metadata visible to the identity itself.

metadata_admin

object

Metadata only accessible through admin APIs.

external_id

string

Optional external ID to link the identity to an external system. Must be unique.

Response

string

The identity’s unique identifier (UUID).

schema_id

string

The JSON Schema ID used for this identity.

traits

object

The identity’s traits.

state

string

The identity’s state (active/inactive).

created_at

string

Timestamp when the identity was created.

Error responses

400: Invalid request body or schema validation failed
409: Identity with duplicate credentials already exists

List identities

curl -X GET "https://{project}.projects.oryapis.com/admin/identities?page_size=100" \
  -H "Authorization: Bearer ory_at_..."

List all identities with optional filtering and pagination.

Query parameters

page_size

integer

default:"250"

Number of items per page (max: 500).

page_token

string

Token for the next page of results.

consistency

string

Read consistency level: strong or eventual.

ids

array

Retrieve specific identities by their UUIDs.

credentials_identifier

string

Filter by exact credential identifier (email, username).

include_credential

array

Include credential details in response (e.g., password, oidc).

organization_id

string

Filter identities by organization.

Response

Returns an array of identity objects.

Get an identity

curl -X GET "https://{project}.projects.oryapis.com/admin/identities/{id}" \
  -H "Authorization: Bearer ory_at_..."

Retrieve a single identity by its ID.

Path parameters

string

required

The identity’s UUID.

Query parameters

include_credential

array

Include credentials in response (e.g., oidc, password).

Error responses

404: Identity not found

Update an identity

curl -X PUT https://{project}.projects.oryapis.com/admin/identities/{id} \
  -H "Authorization: Bearer ory_at_..." \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "default",
    "traits": {
      "email": "[email protected]",
      "name": "Jane Doe"
    },
    "state": "active"
  }'

Update an identity with the full payload. For partial updates, use PATCH instead.

Path parameters

string

required

The identity’s UUID.

Request body

Same as create identity, but credentials are optional and will be imported if provided.

Error responses

400: Invalid request body
404: Identity not found
409: Conflict with existing data

Patch an identity

curl -X PATCH https://{project}.projects.oryapis.com/admin/identities/{id} \
  -H "Authorization: Bearer ory_at_..." \
  -H "Content-Type: application/json" \
  -d '[
    {
      "op": "replace",
      "path": "/traits/email",
      "value": "[email protected]"
    }
  ]'

Partially update an identity using JSON Patch operations. The id, stateChangedAt, and credentials fields cannot be updated.

Request body

Array of JSON Patch operations:

string

required

Operation: add, remove, replace, move, copy, or test.

path

string

required

JSON Pointer to the field (e.g., /traits/email).

value

any

New value for the field.

Delete an identity

curl -X DELETE https://{project}.projects.oryapis.com/admin/identities/{id} \
  -H "Authorization: Bearer ory_at_..."

Permanently delete an identity. This action cannot be undone.

Path parameters

string

required

The identity’s UUID.

Response

Returns 204 No Content on success.

Error responses

404: Identity not found

Delete identity credentials

curl -X DELETE "https://{project}.projects.oryapis.com/admin/identities/{id}/credentials/password" \
  -H "Authorization: Bearer ory_at_..."

Delete a specific credential type for an identity. Cannot delete passkey or code credentials.

Path parameters

string

required

The identity’s UUID.

type

string

required

Credential type: password, oidc, totp, lookup_secret, webauthn, saml.

Query parameters

identifier

string

For OIDC/SAML credentials, specify which provider connection to delete.

List identity sessions

curl -X GET "https://{project}.projects.oryapis.com/admin/identities/{id}/sessions" \
  -H "Authorization: Bearer ory_at_..."

Retrieve all sessions for a specific identity.

Path parameters

string

required

The identity’s UUID.

Query parameters

page_size

integer

default:"250"

Number of items per page.

page_token

string

Token for pagination.

active

boolean

Filter by session state (true for active only).

Response

Returns an array of session objects.

Delete identity sessions

curl -X DELETE https://{project}.projects.oryapis.com/admin/identities/{id}/sessions \
  -H "Authorization: Bearer ory_at_..."

Permanently delete and invalidate all sessions for an identity.

Path parameters

string

required

The identity’s UUID.

Response

Returns 204 No Content on success.

Get identity by external ID

curl -X GET "https://{project}.projects.oryapis.com/admin/identities/by/external/{externalID}" \
  -H "Authorization: Bearer ory_at_..."

Retrieve an identity by its external ID.

Path parameters

externalID

string

required

The external ID of the identity.

Query parameters

include_credential

array

Include credential details in response.

Error responses

404: Identity not found

Admin API

Self-Service API

Frontend API

Create an identity

Request body

Response

Error responses

List identities

Query parameters

Response

Get an identity

Path parameters

Query parameters

Error responses

Update an identity

Path parameters

Request body

Error responses

Patch an identity

Request body

Delete an identity

Path parameters

Response

Error responses

Delete identity credentials

Path parameters

Query parameters

List identity sessions

Path parameters

Query parameters

Response

Delete identity sessions

Path parameters

Response

Get identity by external ID

Path parameters

Query parameters

Error responses

Build docs developers (and LLMs) love

Admin API

Self-Service API

Frontend API

​Create an identity

​Request body

​Response

​Error responses

​List identities

​Query parameters

​Response

​Get an identity

​Path parameters

​Query parameters

​Error responses

​Update an identity

​Path parameters

​Request body

​Error responses

​Patch an identity

​Request body

​Delete an identity

​Path parameters

​Response

​Error responses

​Delete identity credentials

​Path parameters

​Query parameters

​List identity sessions

​Path parameters

​Query parameters

​Response

​Delete identity sessions

​Path parameters

​Response

​Get identity by external ID

​Path parameters

​Query parameters

​Error responses

Build docs developers (and LLMs) love

Create an identity

Request body

Response

Error responses

List identities

Query parameters

Response

Get an identity

Path parameters

Query parameters

Error responses

Update an identity

Path parameters

Request body

Error responses

Patch an identity

Request body

Delete an identity

Path parameters

Response

Error responses

Delete identity credentials

Path parameters

Query parameters

List identity sessions

Path parameters

Query parameters

Response

Delete identity sessions

Path parameters

Response

Get identity by external ID

Path parameters

Query parameters

Error responses