Phase Two API
Phase Two adds resources to Keycloak that the standard admin API does not have — organizations, organization roles, invitations, per-organization identity providers, SCIM, and an event and webhook system. This section documents those endpoints.
It extends the Keycloak Admin REST API rather than replacing it. Realms, clients, users and roles are still managed through Keycloak's own API; everything here sits alongside it on the same server, under the same authentication.
Base URL
Every path is relative to your Keycloak server's realms endpoint:
https://{your-keycloak-host}/realms/{realm}/...
On a Phase Two-hosted cluster that is https://app.phasetwo.io/realms/{realm}/.... Some
deployments serve Keycloak under an /auth prefix, in which case the base becomes
https://{host}/auth/realms/{realm}/.... Self-hosted and local installs work the same way —
these are Keycloak extensions, so they live wherever your Keycloak lives.
Authentication
Every endpoint takes a bearer token:
Authorization: Bearer <access_token>
The token is an ordinary Keycloak access token, so anything that can obtain one will work — a
service account using the client credentials grant, or admin-cli for interactive use. The
permissions required are Keycloak's own: most endpoints need realm-management roles, and the
organization endpoints additionally respect organization role membership.
If you have not obtained a Keycloak token before, the token tutorial walks through it end to end and shows what each claim means.
What is here
84 endpoints across 12 groups.
| Group | Endpoints | What it covers |
|---|---|---|
| Organizations | 12 | Create, read, update and delete organizations; portal links |
| Organization Attributes | 2 | Arbitrary key/value metadata on an organization |
| Organization Memberships | 5 | Add, list, count and remove members |
| Organization Domains | 3 | Claim and verify email domains for an organization |
| Organization Invitation | 9 | Invite users, list and accept invitations |
| Organization Roles | 11 | Define roles within an organization and grant them |
| Active Organization | 2 | Read and switch the caller's active organization |
| Identity Providers | 13 | Per-organization IdPs, mappers and config import |
| Organization SCIM | 4 | Directory sync configuration per organization |
| Users | 5 | User-centric views across organizations |
| Events | 13 | Event storage, webhooks and delivery inspection |
| Attributes | 5 | Realm and resource attribute management |
The OpenAPI specification
The whole surface is described by one spec, which is also what generates these pages:
-
/openapi.yaml— OpenAPI 3, YAML -
/openapi.json— the same document as JSON -
/.well-known/api-catalog— an RFC 9727 linkset pointing at both
Use it to generate a client, drive contract tests, or load into an HTTP client. The reference introduction carries the spec metadata as rendered by the API explorer.
Conventions worth knowing before you start
{realm} is a path segment, not a header. Every organization-scoped call is realm-scoped
first. There is no cross-realm endpoint.
Organization IDs are opaque. Treat {orgId} as a string; do not derive it from a name or
a domain. Look it up, or capture it from the create response.
Pagination is first and max, matching Keycloak's own convention rather than page and
per-page. List endpoints that support it say so, and several groups also expose a dedicated
count endpoint so you do not have to page through everything to get a total.
Errors are Keycloak's errors. A 401 means the token is bad or absent; a 403 means the token is valid but lacks the role. If a call that should work returns 403, check the service account's realm-management roles before anything else.