Create an identity provider

POST

/clusters/{cluster_id}/realms/{realm_name}/identity-providers

const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/realms/customer-portal/identity-providers';
const options = {
  method: 'POST',
  headers: {
    'API-Version': '2026-06-01.beta',
    'API-Key': '<API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"provider_id":"oidc","type":"oidc","display_name":"example","client_id":"example","client_secret":"example","config":{"oidc":{"issuer":"https://accounts.google.com","authorization_url":"https://accounts.google.com/o/oauth2/v2/auth","token_url":"https://oauth2.googleapis.com/token","userinfo_url":"https://openidconnect.googleapis.com/v1/userinfo","logout_url":"https://example.com"},"saml":{"entity_id":"https://idp.example.com/entity","sso_url":"https://idp.example.com/sso/saml","metadata_url":"https://example.com","metadata_xml":"example"},"ldap":{"server_url":"ldaps://ldap.example.com:636","base_dn":"dc=example,dc=com","bind_dn":"cn=skycloak-svc,ou=service-accounts,dc=example,dc=com"},"icon_url":"https://example.com","button_text":"Continue with Okta","attribute_mappings":{"email":"email","firstName":"given_name","lastName":"family_name"},"sync_mode":"import","trust_email":true},"template_id":"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/identity-providers \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta' \
  --header 'Content-Type: application/json' \
  --data '{ "provider_id": "oidc", "type": "oidc", "display_name": "example", "client_id": "example", "client_secret": "example", "config": { "oidc": { "issuer": "https://accounts.google.com", "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth", "token_url": "https://oauth2.googleapis.com/token", "userinfo_url": "https://openidconnect.googleapis.com/v1/userinfo", "logout_url": "https://example.com" }, "saml": { "entity_id": "https://idp.example.com/entity", "sso_url": "https://idp.example.com/sso/saml", "metadata_url": "https://example.com", "metadata_xml": "example" }, "ldap": { "server_url": "ldaps://ldap.example.com:636", "base_dn": "dc=example,dc=com", "bind_dn": "cn=skycloak-svc,ou=service-accounts,dc=example,dc=com" }, "icon_url": "https://example.com", "button_text": "Continue with Okta", "attribute_mappings": { "email": "email", "firstName": "given_name", "lastName": "family_name" }, "sync_mode": "import", "trust_email": true }, "template_id": "example" }'

Adds a new identity provider to the realm. Supply template_id from GET /identity-provider-templates to bootstrap configuration from a pre-built template.

Required scope: identity-providers: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 identity provider.

object

provider_id

required

Skycloak provider ID. Determines the Keycloak provider type and becomes the alias for this provider instance. Must be unique within the realm.

string

Allowed values: oidc saml keycloak-oidc google github microsoft facebook gitlab bitbucket linkedin-openid-connect twitter instagram paypal stackoverflow openshift-v4 google-workspace okta-oidc onelogin-oidc jumpcloud-oidc pingone-oidc auth0 salesforce slack discord atlassian twitch custom-oidc google-workspace-saml okta-saml azure-ad-saml onelogin-saml jumpcloud-saml pingfederate-saml pingone-saml duo-saml cloudflare-saml cyberark-saml custom-saml

type

required

Protocol of the identity provider.

string

Allowed values: oidc saml ldap

display_name

required

string

>= 1 characters <= 255 characters

client_id

OAuth 2.0 / LDAP client identifier registered with the external provider.

string

>= 1 characters <= 1024 characters

client_secret

Client secret or LDAP bind password. Write-only; never returned by the API.

string format: password

>= 1 characters <= 8192 characters

config

Protocol-specific configuration and shared display options. Populate only the sub-object that matches type.

object

oidc

OIDC-specific endpoints. Required when type is oidc.

object

issuer

OIDC issuer identifier URL. Use POST /identity-providers/discover-oidc to fetch endpoints from the issuer automatically.

string format: uri

<= 2048 characters

Example

https://accounts.google.com

authorization_url

Authorization endpoint. Derived from discovery when issuer is supplied.

string format: uri

<= 2048 characters

Example

https://accounts.google.com/o/oauth2/v2/auth

token_url

Token endpoint. Derived from discovery when issuer is supplied.

string format: uri

<= 2048 characters

Example

https://oauth2.googleapis.com/token

userinfo_url

UserInfo endpoint.

string format: uri

<= 2048 characters

Example

https://openidconnect.googleapis.com/v1/userinfo

logout_url

End-session (logout) endpoint.

string format: uri

<= 2048 characters

saml

SAML-specific settings. Required when type is saml.

object

entity_id

SAML entity ID of the external identity provider.

string

<= 512 characters

Example

https://idp.example.com/entity

sso_url

SAML Single Sign-On service URL.

string format: uri

<= 2048 characters

Example

https://idp.example.com/sso/saml

metadata_url

URL to the IdP’s SAML metadata document. Takes precedence over metadata_xml.

string format: uri

<= 2048 characters

metadata_xml

Raw SAML metadata XML. Used when the IdP does not publish a metadata URL.

string

<= 65536 characters

ldap

LDAP-specific settings. Required when type is ldap.

object

server_url

LDAP server URL including scheme and port.

string

<= 512 characters /^ldaps?:///

Example

ldaps://ldap.example.com:636

base_dn

Base Distinguished Name used as the search root.

string

<= 512 characters

Example

dc=example,dc=com

bind_dn

Bind DN used to authenticate against the directory.

string

<= 512 characters

Example

cn=skycloak-svc,ou=service-accounts,dc=example,dc=com

icon_url

URL to the logo displayed on the login button.

string format: uri

<= 2048 characters

button_text

Label of the SSO login button shown to end users.

string

<= 100 characters

Example

Continue with Okta

attribute_mappings

Keycloak attribute name → IdP claim name mappings applied when importing user profiles.

object

key

additional properties

string

Example

{
  "email": "email",
  "firstName": "given_name",
  "lastName": "family_name"
}

sync_mode

string

Allowed values: import force legacy

trust_email

When true, Keycloak trusts email addresses provided by this IdP without sending a verification email. Enable only for providers that verify email addresses themselves.

boolean

template_id

Template ID from GET /identity-provider-templates. When provided, type and config are pre-filled with recommended defaults; explicit fields in this request override template values.

string

>= 1 characters

Responses

201

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

application/json

An identity provider (social login, enterprise SSO, or directory federation) configured in a Keycloak realm.

object

provider_id

required

Keycloak alias. Stable resource identifier for this API. For providers created via Skycloak this is always a SkycloakProviderId value; for externally managed providers it may be any valid alias string.

string

>= 1 characters <= 255 characters /^[a-zA-Z0-9_-]+$/

type

required

Protocol of the identity provider.

string

Allowed values: oidc saml ldap

display_name

required

string

enabled

required

boolean

client_id

Client identifier used to authenticate with the external provider. Not a secret.

string

config

required

Protocol-specific configuration and shared display options. Populate only the sub-object that matches type.

object

oidc

OIDC-specific endpoints. Required when type is oidc.

object

issuer

OIDC issuer identifier URL. Use POST /identity-providers/discover-oidc to fetch endpoints from the issuer automatically.

string format: uri

<= 2048 characters

authorization_url

Authorization endpoint. Derived from discovery when issuer is supplied.

string format: uri

<= 2048 characters

token_url

Token endpoint. Derived from discovery when issuer is supplied.

string format: uri

<= 2048 characters

userinfo_url

UserInfo endpoint.

string format: uri

<= 2048 characters

logout_url

End-session (logout) endpoint.

string format: uri

<= 2048 characters

saml

SAML-specific settings. Required when type is saml.

object

entity_id

SAML entity ID of the external identity provider.

string

<= 512 characters

sso_url

SAML Single Sign-On service URL.

string format: uri

<= 2048 characters

metadata_url

URL to the IdP’s SAML metadata document. Takes precedence over metadata_xml.

string format: uri

<= 2048 characters

metadata_xml

Raw SAML metadata XML. Used when the IdP does not publish a metadata URL.

string

<= 65536 characters

ldap

LDAP-specific settings. Required when type is ldap.

object

server_url

LDAP server URL including scheme and port.

string

<= 512 characters /^ldaps?:///

base_dn

Base Distinguished Name used as the search root.

string

<= 512 characters

bind_dn

Bind DN used to authenticate against the directory.

string

<= 512 characters

icon_url

URL to the logo displayed on the login button.

string format: uri

<= 2048 characters

button_text

Label of the SSO login button shown to end users.

string

<= 100 characters

attribute_mappings

Keycloak attribute name → IdP claim name mappings applied when importing user profiles.

object

key

additional properties

string

sync_mode

string

Allowed values: import force legacy

trust_email

When true, Keycloak trusts email addresses provided by this IdP without sending a verification email. Enable only for providers that verify email addresses themselves.

boolean

externally_managed

required

When true, this provider was created or last modified directly in the Keycloak Admin Console. Skycloak reflects its configuration but PATCH and DELETE will return 403 Forbidden.

boolean

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "provider_id": "google-workspace",
  "type": "oidc",
  "config": {
    "oidc": {
      "issuer": "https://accounts.google.com",
      "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth",
      "token_url": "https://oauth2.googleapis.com/token",
      "userinfo_url": "https://openidconnect.googleapis.com/v1/userinfo"
    },
    "saml": {
      "entity_id": "https://idp.example.com/entity",
      "sso_url": "https://idp.example.com/sso/saml"
    },
    "ldap": {
      "server_url": "ldaps://ldap.example.com:636",
      "base_dn": "dc=example,dc=com",
      "bind_dn": "cn=skycloak-svc,ou=service-accounts,dc=example,dc=com"
    },
    "button_text": "Continue with Okta",
    "attribute_mappings": {
      "email": "email",
      "firstName": "given_name",
      "lastName": "family_name"
    },
    "sync_mode": "import"
  }
}

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 identity provider

Authorizations

Parameters

Path Parameters

Example

Header Parameters

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

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