Admin API v2

REST API for managing Keycloak resources. Experimental feature.
This feature is experimental and may introduce breaking changes in future versions of Keycloak. Do not use this feature in production environments.

Prerequisites

The Admin API v2 requires the client-admin-api-v2 feature:

bin/kc.[sh|bat] start --features=client-admin-api-v2

Client Setup

Java

Add the dependency to your project:

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
</dependency>
import org.keycloak.admin.client.Keycloak;

Keycloak adminClient = Keycloak.getInstance("http://localhost:8080", "master", "admin", "password", "admin-cli");

JavaScript

npm install @keycloak/keycloak-admin-client
import KcAdminClient from "@keycloak/keycloak-admin-client";

const kcAdminClient = new KcAdminClient({ baseUrl: "http://localhost:8080", enableExperimentalApis: true });
await kcAdminClient.auth({ username: "admin", password: "admin", grantType: "password", clientId: "admin-cli" });

CLI

The Admin API v2 uses the same CLI tool described in the Server Administration Guide with the --v2 flag:

bin/kcadm.[sh|bat] --v2 config credentials --server http://localhost:8080 --realm master --user admin

Available Resources

Clients

Java Client Setup

import org.keycloak.admin.api.client.ClientsApi;
import org.keycloak.admin.api.AdminApi;

AdminApi adminApi = adminClient.proxy(AdminApi.class);
ClientsApi clientsApi = adminApi.clientsV2();

GET /admin/api/{realmName}/clients/v2

Get all clients

Returns a list of clients in the realm, optionally filtered by a query expression

HTTP Request
GET /admin/api/{realmName}/clients/v2 HTTP/1.1
Path Parameters
Name Description

realmName
required
Query Parameters
Name Description

fields

Set of fields to include in the response. Must be top-level fields. If omitted or empty, all fields will be populated.

q

Filter expression using SCIM-like syntax, e.g. clientId eq "my-app" and enabled eq true
Responses
Code Type Description

200

array<OIDCClientRepresentation>, array<SAMLClientRepresentation>

OK
Examples

CLI

kcadm.sh --v2 client list

Java

clientsApi.getClients(params);

JavaScript

kcAdminClient.clients.v2().get();

POST /admin/api/{realmName}/clients/v2

Create a new client

Creates a new client in the realm

HTTP Request
POST /admin/api/{realmName}/clients/v2 HTTP/1.1
Content-Type: application/json
Path Parameters
Name Description

realmName
required
Body Parameter
Name protocol

OIDCClientRepresentation
required

openid-connect

SAMLClientRepresentation
required

saml
Responses
Code Type Description

201

OIDCClientRepresentation, SAMLClientRepresentation

Created
Examples

CLI

kcadm.sh --v2 client create -f client.json

Java

clientsApi.createClient(client);

JavaScript

kcAdminClient.clients.v2().post(requestBody);

GET /admin/api/{realmName}/clients/v2/{id}

Get a client

Returns a single client by its clientId

HTTP Request
GET /admin/api/{realmName}/clients/v2/{id} HTTP/1.1
Path Parameters
Name Description

realmName
required

id
required
Responses
Code Type Description

200

OIDCClientRepresentation, SAMLClientRepresentation

OK

404

Not Found
Examples

CLI

kcadm.sh --v2 client get CLIENT_ID

Java

clientsApi.client(id).getClient();

JavaScript

kcAdminClient.clients.v2().byId(id).get();

PUT /admin/api/{realmName}/clients/v2/{id}

Create or update a client

Creates or updates a client in the realm

HTTP Request
PUT /admin/api/{realmName}/clients/v2/{id} HTTP/1.1
Content-Type: application/json
Path Parameters
Name Description

realmName
required

id
required
Body Parameter
Name protocol

OIDCClientRepresentation
required

openid-connect

SAMLClientRepresentation
required

saml
Responses
Code Type Description

200

OIDCClientRepresentation, SAMLClientRepresentation

OK

201

OIDCClientRepresentation, SAMLClientRepresentation

Created
Examples

CLI

kcadm.sh --v2 client apply CLIENT_ID -f client.json

Java

clientsApi.client(id).createOrUpdateClient(client);

JavaScript

kcAdminClient.clients.v2().byId(id).put(requestBody);

PATCH /admin/api/{realmName}/clients/v2/{id}

Patch a client

Partially updates a client using JSON Merge Patch

HTTP Request
PATCH /admin/api/{realmName}/clients/v2/{id} HTTP/1.1
Content-Type: application/merge-patch+json
Path Parameters
Name Description

realmName
required

id
required
Body Parameter

A partial representation containing the fields to update. Required fields must always be included.

Name protocol

OIDCClientRepresentation

openid-connect

SAMLClientRepresentation

saml
Responses
Code Type Description

200

OIDCClientRepresentation, SAMLClientRepresentation

OK

404

Not Found
Examples

CLI

kcadm.sh --v2 client patch CLIENT_ID -f client.json

Java

clientsApi.client(id).patchClient(patch);

JavaScript

kcAdminClient.clients.v2().byId(id).patch(requestBody);

DELETE /admin/api/{realmName}/clients/v2/{id}

Delete a client

Deletes a client from the realm

HTTP Request
DELETE /admin/api/{realmName}/clients/v2/{id} HTTP/1.1
Path Parameters
Name Description

realmName
required

id
required
Responses
Code Type Description

204

Client successfully deleted

404

Not Found
Examples

CLI

kcadm.sh --v2 client delete CLIENT_ID

Java

clientsApi.client(id).deleteClient();

JavaScript

kcAdminClient.clients.v2().byId(id).delete();

Models

BaseClientRepresentation

Name Type Description

uuid
read-only

string

UUID generated by the server. Validation: on update/on patch: UUID is server-managed and must not be user-specified

clientId
required

string

ID uniquely identifying this client. Validation: must not be blank; size must be between 1 and 255

displayName

string

Human readable name of the client. Validation: size must be between 0 and 255

description

string

Human readable description of the client. Validation: size must be between 0 and 255

enabled

boolean

Whether this client is enabled

appUrl

string

URL to the application’s homepage that is represented by this client. Validation: size must be between 0 and 255; must be a valid URL

redirectUris

array<string>

URIs that the browser can redirect to after login. Validation: size must be between 0 and 100; each element must not be blank, size must be between 0 and 255; Invalid redirect URI

roles

array<string>

Roles associated with this client. Validation: size must be between 0 and 300; each element must not be blank, size must be between 0 and 255

protocol

string

Discriminator. Allowed values: openid-connect, saml

OIDCClientRepresentation

Extends BaseClientRepresentation.

Name Type Description

loginFlows

array<Flow>

Login flows that are enabled for this client. Validation: SERVICE_ACCOUNT and TOKEN_EXCHANGE flows require a confidential client (auth must be specified); STANDARD and IMPLICIT flows require at least one redirect URI

auth

Auth

Authentication configuration for this client

webOrigins

array<string>

Web origins that are allowed to make requests to this client. Validation: size must be between 0 and 100; each element must not be blank, size must be between 0 and 255, must be a valid web origin (scheme://host[:port]), or '+' to derive from redirect URIs, or '*' to allow all

serviceAccountRoles

array<string>

Roles assigned to the service account. Validation: size must be between 0 and 300; each element must not be blank, size must be between 0 and 255; serviceAccountRoles can only be set when SERVICE_ACCOUNT flow is enabled

protocol

string

Fixed value: openid-connect

Flow

Enum values: STANDARD, IMPLICIT, DIRECT_GRANT, SERVICE_ACCOUNT, TOKEN_EXCHANGE, DEVICE, CIBA

Auth

Name Type Description

method
required

string

Which authentication method is used for this client. Validation: must not be blank; valid client authenticator type is required

secret

string

Secret used to authenticate this client with Secret authentication. Validation: size must be between 6 and 255; on update: Client secret must not be blank

certificate

string

Public key used to authenticate this client with Signed JWT authentication. Validation: size must be between 0 and 65536

SAMLClientRepresentation

Extends BaseClientRepresentation.

Name Type Description

nameIdFormat

NameIdFormat

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

forcePostBinding

boolean

Force POST binding for SAML responses

frontChannelLogout

boolean

Use front-channel logout (browser redirect)

signatureAlgorithm

SignatureAlgorithm

Signature algorithm for signing SAML documents

signatureCanonicalizationMethod

string

Canonicalization method for XML signatures. Validation: must be a valid XML canonicalization method URI (see javax.xml.crypto.dsig.CanonicalizationMethod constants)

signingCertificate

string

X.509 certificate for signing (PEM format, without headers). Validation: size must be between 0 and 65536

allowEcpFlow

boolean

Allow ECP (Enhanced Client or Proxy) flow

protocol

string

Fixed value: saml

NameIdFormat

Enum values: username, email, persistent, transient

SignatureAlgorithm

Enum values: RSA_SHA1, RSA_SHA256, RSA_SHA256_MGF1, RSA_SHA512, RSA_SHA512_MGF1, DSA_SHA1

On this page
Edit this guide