Connections API

Create, test, and manage SAML and OIDC connections — each one provisions a Keycloak identity provider.

All routes live under /api/v1/connections. Unlike Accounts, this module accepts either credential type: if an X-API-Key header is present it is authenticated as an API key, otherwise as a vendor session. See SSO Connections for how the resulting Keycloak identity provider actually brokers a login, and SAML 2.0 for the customer-facing side of setup.

Create a SAML connection

POST/api/v1/connections/saml

Field	Type	Notes
accountId	string	Required
name	string	Required
metadataUrl	string (URL)	Optional — IdP metadata URL
metadataXml	string	Optional — raw IdP metadata XML
idpEntityId	string	Optional — customer IdP's entity ID, used if not parsed from metadata
idpSsoUrl	string (URL)	Optional — customer IdP's SSO endpoint
idpCertificate	string	Optional — customer IdP's signing certificate
entityId	string	Optional — our SP entity ID; generated from the account slug if omitted
acsUrl	string (URL)	Optional — our ACS URL; generated if omitted

One of metadataUrl/metadataXml or the idp* fields must be supplied — a connection without either cannot broker a login. On success, RealmSSO provisions a Keycloak identity provider (alias saml-<account-slug>-<id prefix>) in the account's realm and returns the connection together with its ssoConfig. If Keycloak provisioning fails, the connection is still created but with status: "error" rather than "active" — the request itself does not fail.

Create an OIDC connection

POST/api/v1/connections/oidc

Field	Type	Notes
accountId	string	Required
name	string	Required
clientId	string	Required
clientSecret	string	Required — encrypted at rest, never returned or logged in audit details
discoveryUrl	string (URL)	Required — the customer IdP's OIDC discovery document

Same provisioning behavior as SAML: creates a Keycloak identity provider (alias oidc-<account-slug>-<id prefix>), and the redirect URI the customer must register is Keycloak's broker endpoint, not a RealmSSO route.

List connections

GET/api/v1/connections

Requires an accountId query parameter (400 without it). Optional type (saml/oidc) and status filters, plus page/limit pagination (max 100). Each result includes its ssoConfigs.

Get / update / delete a connection

GET/api/v1/connections/:id

PATCH/api/v1/connections/:id

DELETE/api/v1/connections/:id

PATCH accepts a partial body covering name, status, and any of the SAML/OIDC fields above (all nullable); a new clientSecret is re-encrypted before storage and never appears in the audit log. DELETE removes the Keycloak identity provider first and only deletes the database row once that succeeds — leaving a stale Keycloak IdP behind would strand a login path nothing in the database could point at again.

Test connection health

POST/api/v1/connections/:id/test

The per-connection health check: runs a reachability test against the provisioned Keycloak identity provider and updates healthStatus (healthy/down) and lastHealthCheckAt on the connection. Returns 400 if the connection was never successfully provisioned in Keycloak.

{
  "data": { "reachable": true, "latencyMs": 84 }
}

Get connection config

GET/api/v1/connections/:id/config

Returns the display-friendly SSO details (ACS URL / entity ID / issuer for SAML, client ID / discovery URL / redirect URIs for OIDC) used to render setup instructions in the Admin Portal — never the encrypted client secret.

API key scope

A caller authenticating with an API key must still hold access to the connection's accountId — the key is only valid for the account it was issued to. See API Overview for how API keys and scopes work.

← Accounts API SCIM API →