Create an application

POST

/clusters/{cluster_id}/realms/{realm_name}/applications

const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/realms/customer-portal/applications';
const options = {
  method: 'POST',
  headers: {
    'API-Version': '2026-06-01.beta',
    'API-Key': '<API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"client_id":"example","name":"example","description":"example","type":"confidential","protocol":"openid-connect","status":"active","redirect_uris":["example"],"grant_types":["authorization_code"],"pkce_required":false,"consent_required":false,"saml_config":{"entity_id":"example","assertion_consumer_urls":["example"],"single_logout_service_url":"example","name_id_format":"urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified","sign_documents":true,"sign_assertions":true,"encrypt_assertions":true,"force_authn":true,"force_post_binding":true,"include_authn_statement":true,"attribute_statements":{"additionalProperty":"example"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/realms/customer-portal/applications \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta' \
  --header 'Content-Type: application/json' \
  --data '{ "client_id": "example", "name": "example", "description": "example", "type": "confidential", "protocol": "openid-connect", "status": "active", "redirect_uris": [ "example" ], "grant_types": [ "authorization_code" ], "pkce_required": false, "consent_required": false, "saml_config": { "entity_id": "example", "assertion_consumer_urls": [ "example" ], "single_logout_service_url": "example", "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified", "sign_documents": true, "sign_assertions": true, "encrypt_assertions": true, "force_authn": true, "force_post_binding": true, "include_authn_statement": true, "attribute_statements": { "additionalProperty": "example" } } }'

Registers a new Keycloak client in the realm.

Required scope: applications:write

Authorizations

ApiKeyAuth

Parameters

Path Parameters

cluster_id

required

string format: uuid

realm_name

required

Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.

string

>= 1 characters <= 63 characters /^[a-zA-Z][a-zA-Z0-9-]*$/

Example

customer-portal

Header Parameters

API-Version

required

string

Allowed values: 2026-06-01.beta

Request Body^required

application/json

Request body for creating a new application.

object

client_id

required

OAuth 2.0 client identifier. Must be unique within the realm.

string

>= 1 characters <= 255 characters

name

required

Human-readable display name.

string

description

Optional description.

string

type

OAuth 2.0 client type. Defaults to confidential.

string

Allowed values: confidential public

protocol

Authentication protocol. Defaults to openid_connect.

string

Allowed values: openid-connect saml

status

Initial status. Defaults to active.

string

Allowed values: active inactive

redirect_uris

Allowed redirect URIs. Required when grant_types includes authorization_code.

Array<string>

grant_types

required

Enabled OAuth 2.0 grant types.

Array<string>

Allowed values: authorization_code implicit password client_credentials refresh_token

pkce_required

Whether PKCE is required. Defaults to false.

boolean

consent_required

Whether user consent is required. Defaults to false.

boolean

saml_config

SAML configuration. Required when protocol is saml.

object

entity_id

SAML entity ID (SP Entity ID / Issuer).

string

assertion_consumer_urls

Assertion Consumer Service URLs (ACS endpoints).

Array<string>

single_logout_service_url

Single Logout Service URL.

string

name_id_format

SAML NameID format.

string

Allowed values: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress urn:oasis:names:tc:SAML:2.0:nameid-format:persistent urn:oasis:names:tc:SAML:2.0:nameid-format:transient

sign_documents

Whether to sign SAML documents.

boolean

sign_assertions

Whether to sign SAML assertions.

boolean

encrypt_assertions

Whether to encrypt SAML assertions.

boolean

force_authn

Whether to force re-authentication on each request.

boolean

force_post_binding

Whether to force HTTP POST binding for responses.

boolean

include_authn_statement

Whether to include the AuthnStatement in assertions.

boolean

attribute_statements

Static SAML attribute statements to include in assertions. Keys are attribute names; values are attribute values.

object

key

additional properties

string

Responses

201

The request has succeeded and a new resource has been created as a result.

application/json

A Keycloak client (application) registered in a realm.

object

client_id

required

OAuth 2.0 client identifier. Stable resource identifier for this API.

string

>= 1 characters <= 255 characters

name

required

Human-readable display name.

string

description

Optional description of the application.

string

type

required

OAuth 2.0 client type.

string

Allowed values: confidential public

protocol

required

Authentication protocol.

string

Allowed values: openid-connect saml

status

required

Whether the application is active.

string

Allowed values: active inactive

redirect_uris

required

Allowed redirect URIs for authorization-code flows. Required for authorization_code grant.

Array<string>

grant_types

required

Enabled OAuth 2.0 grant types.

Array<string>

Allowed values: authorization_code implicit password client_credentials refresh_token

pkce_required

required

Whether PKCE (Proof Key for Code Exchange) is required.

boolean

consent_required

required

Whether user consent is required before issuing tokens.

boolean

service_account_enabled

required

Whether this application has a service account for machine-to-machine flows. Derived from the client_credentials grant type.

boolean

client_secret

Client secret. Present only immediately after creation or secret rotation; store it securely as it will not be returned again.

string format: password

web_origins

Browser origins allowed to call this application (CORS). ["*"] allows any origin.

Array<string>

post_logout_redirect_uris

URIs a user may be redirected to after signing out. Falls back to redirect_uris when empty.

Array<string>

root_url

Root URL. Prefixed to any relative redirect URI.

string

base_url

Home URL. Where Keycloak sends a user opening the application from the account console.

string

admin_url

Admin URL. Where Keycloak sends back-channel logout and admin callbacks.

string

saml_config

SAML-specific configuration. Present only when protocol is saml.

object

entity_id

SAML entity ID (SP Entity ID / Issuer).

string

assertion_consumer_urls

Assertion Consumer Service URLs (ACS endpoints).

Array<string>

single_logout_service_url

Single Logout Service URL.

string

name_id_format

SAML NameID format.

string

sign_documents

Whether to sign SAML documents.

boolean

sign_assertions

Whether to sign SAML assertions.

boolean

encrypt_assertions

Whether to encrypt SAML assertions.

boolean

force_authn

Whether to force re-authentication on each request.

boolean

force_post_binding

Whether to force HTTP POST binding for responses.

boolean

include_authn_statement

Whether to include the AuthnStatement in assertions.

boolean

attribute_statements

Static SAML attribute statements to include in assertions. Keys are attribute names; values are attribute values.

object

key

additional properties

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "type": "confidential",
  "protocol": "openid-connect",
  "status": "active",
  "grant_types": [
    "authorization_code"
  ],
  "saml_config": {
    "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
  }
}

400

The server could not understand the request due to invalid syntax.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

401

Access is unauthorized.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

402

Client error

application/problem+json

Returned when a workspace plan quota would be exceeded. required_plan indicates the minimum plan needed to complete the request.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

current_plan

required

string

required_plan

required

string

code

Machine-readable identifier of the quota that was hit, so a client can tell quotas apart without parsing detail. Known values include cluster_limit (the workspace’s total cluster allowance), cluster_size_quota (the allowance for the requested cluster size) and cluster_size (the requested size is not offered on the plan at all). New values may be added.

string

current_usage

How many of the resource the workspace currently has.

integer

current_limit

Maximum allowed by the current plan. 0 means the plan does not include the resource at all.

integer

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "current_plan": "example",
  "required_plan": "example",
  "code": "example",
  "current_usage": 1,
  "current_limit": 1
}

403

Access is forbidden.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

404

The server cannot find the requested resource.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

409

The request conflicts with the current state of the server.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

422

Client error

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

errors

required

Array<object>

>= 1 items

object

field

required

string

detail

required

string

code

string

value

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "errors": [
    {
      "field": "example",
      "detail": "example",
      "code": "example",
      "value": "example"
    }
  ]
}

429

Client error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Headers

Retry-After

integer

RateLimit-Limit

integer

RateLimit-Remaining

integer

RateLimit-Reset

integer

X-RateLimit-Limit-Second

integer

X-RateLimit-Remaining-Second

integer

X-RateLimit-Limit-Minute

integer

X-RateLimit-Remaining-Minute

integer

X-RateLimit-Limit-Hour

integer

X-RateLimit-Remaining-Hour

integer

X-RateLimit-Limit-Day

integer

X-RateLimit-Remaining-Day

integer

500

Server error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

501

Server error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Create an application

Authorizations

Parameters

Path Parameters

Example

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Example generated

401

Example generated

402

Example generated

403

Example generated

404

Example generated

409

Example generated

422

Example generated

429

Example generated

Headers

500

Example generated

501

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated