Speak at KeycloakCon Europe 2027 in Barcelona! CfP closes October 18 · Save the date: March 15, 2027 · Submit Today →

Admin API v2: Filtering and Projection

Filter and project client resources using the Admin API v2 query syntax.
This guide is describing a feature which is currently in preview. Please provide your feedback while we’re continuing to work on this.

The Admin API v2 supports filtering clients using the q query parameter. The filter syntax is a subset of the SCIM filter syntax defined in RFC 7644, Section 3.4.2.2. All string comparisons are case-sensitive.

GET /admin/api/{realmName}/clients/v2?q=<filter-expression>

String values must be enclosed in double quotes. Boolean values are unquoted.

GET /admin/api/{realmName}/clients/v2?q=clientId eq "my-app"
GET /admin/api/{realmName}/clients/v2?q=enabled eq true

Supported operators

The following comparison operators are supported for client filtering:

Operator Meaning Example

eq

Equal

clientId eq "my-app"

ne

Not equal

protocol ne "saml"

co

Contains (substring)

description co "oauth"

sw

Starts with

clientId sw "query-"

ew

Ends with

clientId ew "-app"

pr

Present (field is not null)

description pr

Logical operators (and, or, not) and parentheses for grouping are supported. For the full syntax reference, including operator precedence and detailed examples, see the SCIM filtering guide in the Server Administration Guide.

The gt, ge, lt, and le operators supported by the SCIM API are not available for client filtering.

Fields without a value

A comparison with a field that has no value is never true, and for every searchable field except roles the negated comparison is not true either. For example, neither auth.method ne "client-secret" nor not (auth.method eq "client-secret") returns SAML clients or public clients, because they have no authentication method. Use not auth.method pr to find them. The roles field is multi-valued: roles ne "admin" does not return clients without roles, but not (roles eq "admin") does, as described in Collection field matching.

The eq and ne operators accept the null literal, but a comparison such as description eq null never matches any client, so it cannot be used to find clients where the field is absent. For details, see Attributes without a value in the Server Administration Guide.

Queryable fields

Only the fields listed below can be used in filter expressions. Other fields of the client representation are not searchable. Using an unsearchable or unknown field returns HTTP 400, unlike the SCIM API which silently ignores unrecognized attributes.

Common fields (all client types)

Field Type Description

clientId

String

ID uniquely identifying this client

displayName

String

Human readable name of the client

description

String

Human readable description of the client

enabled

Boolean

Whether this client is enabled

appUrl

String

URL to the application’s homepage that is represented by this client

roles

Set<String>

Roles associated with this client

protocol

String

Discriminator. Allowed values: openid-connect, saml

createdTimestamp

Integer

Timestamp when the client was created

updatedTimestamp

Integer

Timestamp when the client was last updated

OIDC-specific fields

These fields are available only for openid-connect clients. They resolve to null for SAML clients, so value-based comparisons like eq, ne, co, or sw do not match SAML clients. See Fields without a value.

Field Type Description

auth.method

String

Client authentication method (e.g. client-secret, client-secret-jwt)

Collection field matching

For multi-valued fields (type Set<String> in the tables above), the eq, co, sw, and ew operators match if any element in the collection satisfies the condition:

  • roles eq "admin" - matches clients that have a role named admin

  • roles co "adm" - matches clients that have a role whose name contains adm

The ne operator matches if any element in the collection differs from the value. For example, roles ne "admin" matches clients that have at least one role other than admin, and it does not match clients without roles. To find clients that do not have a given role, negate the equality instead: not (roles eq "admin"). This form also matches clients without roles.

To match clients that have multiple values, combine conditions with and:

q=roles eq "admin" and roles eq "user"

Examples

Find all enabled OIDC clients:

GET /admin/api/{realmName}/clients/v2?q=protocol eq "openid-connect" and enabled eq true

Find clients with a description:

GET /admin/api/{realmName}/clients/v2?q=description pr

Find OIDC clients using client-secret authentication:

GET /admin/api/{realmName}/clients/v2?q=auth.method eq "client-secret"

Find clients by display name prefix, excluding a specific protocol:

GET /admin/api/{realmName}/clients/v2?q=displayName sw "My" and protocol ne "saml"

Projection

Use the fields query parameter to include only specific fields in the response. If omitted, all fields are returned.

GET /admin/api/{realmName}/clients/v2?fields=clientId,enabled,protocol

Filtering and projection can be combined. The filter evaluates against the full representation before projection is applied, so filtered fields do not need to be included in the projection:

GET /admin/api/{realmName}/clients/v2?q=enabled eq true&fields=clientId,displayName

Error handling

The server returns HTTP 400 with a descriptive error message when:

  • The filter expression has a syntax error.

  • The filter references an unknown field.

  • The filter references a field that is not searchable.

  • The filter uses an unsupported operator (e.g. gt, ge, lt, le).

  • The filter uses null with an operator other than eq or ne.

{
  "error": "Unknown query field: unknownField"
}
On this page
Edit this guide