Join us at KeycloakCon Japan 2026, colocated with KubeCon Japan 2026 · July 28 · Register Today →

Admin API v2: Filtering and Projection

Filter and project client resources using the Admin API v2 query syntax.
This feature is experimental and may introduce breaking changes in future versions of Keycloak. Do not use this feature in production environments.

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.

Queryable fields

Only registered fields can be used in filter expressions. Using an unknown field returns HTTP 400, unlike the SCIM API which silently ignores unrecognized attributes.

Common fields (all client types)

Field Type Description

protocol

String

Discriminator. Allowed values: openid-connect, saml

uuid

String

UUID generated by the server

enabled

Boolean

Whether this client is enabled

clientId

String

ID uniquely identifying this client

description

String

Human readable description of the client

displayName

String

Human readable name of the client

appUrl

String

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

redirectUris

Set<String>

URIs that the browser can redirect to after login

roles

Set<String>

Roles associated with this client

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, co, or sw will not match. However, eq null and not …​ pr will match because the field is genuinely absent.

Field Type Description

loginFlows

Set<String>

Login flows that are enabled for this client

auth.method

String

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

webOrigins

Set<String>

Web origins that are allowed to make requests to this client

serviceAccountRoles

Set<String>

Roles assigned to the service account

SAML-specific fields

These fields are available only for saml clients. They resolve to null for OIDC clients, so value-based comparisons like eq, co, or sw will not match. However, eq null and not …​ pr will match because the field is genuinely absent.

Field Type Description

nameIdFormat

String

Name ID format to use for the subject

forceNameIdFormat

Boolean

Force the specified Name ID format even if the client requests a different one

includeAuthnStatement

Boolean

Include AuthnStatement in the SAML response

signDocuments

Boolean

Sign SAML documents on the server side

signAssertions

Boolean

Sign SAML assertions

clientSignatureRequired

Boolean

Require client to sign SAML requests

signatureAlgorithm

String

Signature algorithm for signing SAML documents

signatureCanonicalizationMethod

String

Canonicalization method for XML signatures

signingCertificate

String

X.509 certificate for signing (PEM format, without headers)

forcePostBinding

Boolean

Force POST binding for SAML responses

frontChannelLogout

Boolean

Use front-channel logout (browser redirect)

allowEcpFlow

Boolean

Allow ECP (Enhanced Client or Proxy) flow

Collection field matching

For fields that hold a collection of values (redirectUris, roles, loginFlows, webOrigins, serviceAccountRoles), 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

  • redirectUris co "example.com" - matches clients with any redirect URI containing example.com

  • loginFlows eq "SERVICE_ACCOUNT" - matches OIDC clients with the service account flow enabled

The ne operator is the logical negation of eq: it matches if no element in the collection equals the value. For example, roles ne "admin" matches clients that do not have a role named admin.

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 SAML clients with document signing enabled:

GET /admin/api/{realmName}/clients/v2?q=signDocuments eq true

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 uses an unsupported operator (e.g. gt, ge, lt, le).

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