v1

latestSwagger 2.02026-07-1760185352.5 KB

identity

List Identities

Lists all identities in the system. Note: filters cannot be combined.

get/admin/identities

Query parameters

per_pageinteger

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.

pageinteger

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.

page_sizeinteger

Page Size

This is the number of items per page to return. For details on pagination please head over to the pagination documentation.

page_tokenstring

Next Page Token

The next page token. For details on pagination please head over to the pagination documentation.

consistency'' | 'strong' | 'eventual'

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.

idsstring[]

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).

credentials_identifierstring

CredentialsIdentifier is the identifier (username, email) of the credentials to look up using exact match. Only one of CredentialsIdentifier and CredentialsIdentifierSimilar can be used.

preview_credentials_identifier_similarstring

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.

include_credentialstring[]

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.

organization_idstring

List identities that belong to a specific organization.

Response

Paginated Identity List Response

created_atstring date-time

CreatedAt is a helper struct field for gobuffalo.pop.

credentialsobject

Credentials represents all credentials that can be used for authenticating this identity.

external_idstring

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.

idstring uuid required

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.

metadata_adminNullJsonRawMessage

NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-

metadata_publicNullJsonRawMessage

NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-

Region is the Ory Network region this identity is homed in. Set by the multi-region persister; empty on OSS and single-region deployments. eu-central EUCentral asia-northeast AsiaNorthEast us-east USEast us-west USWest eu EU asia Asia us US global Global

schema_idstring required

SchemaID is the ID of the JSON Schema to be used for validating the identity's traits.

schema_urlstring required

SchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from.

format: url

state'active' | 'inactive'

State is the identity's state.

This value has currently no effect. active StateActive inactive StateInactive

state_changed_atstring date-time

traitsIdentityTraits required

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_atstring date-time

UpdatedAt is a helper struct field for gobuffalo.pop.

Example response

[
  {
    "verifiable_addresses": [
      {
        "created_at": "2014-01-01T23:28:56.782Z",
        "updated_at": "2014-01-01T23:28:56.782Z",
        "verified": true,
        "via": "email"
      }
    ]
  }
]