Phase Two APIs

Phase Two exposes two APIs. They do unrelated jobs, run on different servers, and take different credentials. Picking the wrong one is the most common way to lose an afternoon here, so start with the table.

	Management API	Extensions API
Manages	Clusters themselves	What runs inside a realm
Server	Phase Two control plane	Your own Keycloak
Host	api.phasetwo.io	<your-cluster-host>
Credential	An API secret from the Phase Two console	A Keycloak token from your realm
Exists when	You have a Phase Two account	You run Phase Two's Keycloak build
Endpoints	73	84

The distinction in one paragraph

The Management API is the API version of the Phase Two console. It creates clusters, adds realms to them, attaches custom domains, uploads extensions, sets environment variables, and reads billing. It never touches the contents of a realm — it has no concept of a user, a client, or an authentication flow.

The Extensions API is the opposite. It knows nothing about clusters, billing, or provisioning. It adds resources to Keycloak that stock Keycloak lacks — organizations, organization roles, invitations, per-organization identity providers, SCIM, and an event and webhook system — and it lives on whichever Keycloak you point it at, hosted by us or not.

An analogy: the Management API is your cloud provider's console; the Extensions API is ssh-ing into the box.

Which one do I want?

"Create me a cluster / a realm / a custom domain." → Management API.

"Add a user to an organization / invite someone / configure SSO for a tenant." → Extensions API.

"Automate everything from CI." → Probably both, in that order. The Management API creates the realm; the Extensions API (and Keycloak's own Admin REST API) configures it. The Terraform provider does the first half declaratively.

"Set up an SSO connection for one of my customers." → Extensions API. Nothing about that requires the control plane.

One name, two meanings

Both APIs use the word extension, unavoidably and confusingly.

In the Management API, an extensions endpoint manages a custom .jar or theme you upload to a cluster — a Keycloak provider you wrote, deployed onto your instance.

In the Extensions API, "extension" refers to Phase Two's own additions to Keycloak, which are what that API consists of.

So: Management API extensions = your code going onto a cluster. Extensions API = our code already on it.

Authentication, briefly

They do not share credentials, and a token for one is worthless to the other.

The Management API uses an OAuth2 client credentials grant against the Phase Two control plane. You create an API secret in the console, exchange it for a token, and call api.phasetwo.io. The API keys guide walks through it.

The Extensions API uses an ordinary Keycloak access token from your realm — the same token that works against Keycloak's Admin REST API, because these endpoints sit alongside it on the same server under the same authentication. The token tutorial covers obtaining one.

Specifications

Both are generated from OpenAPI 3 documents, which are also what generate these pages:

API	YAML	JSON
Management	/openapi-management.yaml	/openapi-management.json
Extensions	/openapi.yaml	/openapi.json

There is also an RFC 9727 linkset at /.well-known/api-catalog pointing at all four documents.

Use them to generate a client, drive contract tests, or load into an HTTP client. For the Management API specifically, we already publish a Terraform provider generated from the spec, so check that before writing your own client.