API/v2/sso-connections

SSO Connections API

An SSO connection is the identity provider that visitors of a private status page sign in with. Create one, then set its uuid as authentication.sso_connection_uuid of a status page. One connection can protect several pages.

ℹ️Base URL

https://api.hyperping.io

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

Header

Authorization: Bearer $USER_API_KEY

API tokens are set at the project level, and these endpoints only see the connections of the key's project. To obtain your API token, go to the Developers tab in your project settings. Creating, updating and deleting need a key with write permissions.

What the API can change

The API reads every connection of the project, whatever its type, so a SAML connection set up in the dashboard can still be linked to a page by its uuid. It creates, updates and deletes OpenID Connect connections only (provider = oidc): Auth0, Okta, Microsoft Entra ID, Keycloak and any other OpenID Connect provider. SAML and Other providers connections are set up in the dashboard, as the status page SSO guide explains.

The identity provider is checked before anything is saved. Hyperping fetches the issuer's discovery document and checks the client ID and secret with it. A configuration the identity provider refuses fails with 400 and creates or changes nothing.
The client secret is write-only. It is never returned: responses only say whether one is saved (has_client_secret).
Register the redirect_uri in your identity provider as an allowed callback URL. It is https://api.hyperping.io/v1/auth/sso/oidc/callback, or https://api.eu.hyperping.io/v1/auth/sso/oidc/callback for EU accounts, and every response includes it.
Billing. A connection created through the API is billed exactly like one created in the dashboard: $49 per month (€49 on EUR billing), or included on plans that include SSO connections. Deleting it stops the charge.

The connection object

Fieldsapplication/json

uuidstring

Identifier of the connection (sso_…). Set it as authentication.sso_connection_uuid when you create or update a status page.

namestring

Name of the connection, shown in the dashboard.

providerenum<string>

Connection type. oidc is OpenID Connect; azure, okta, google and saml are SAML connections; workos is an Other providers connection set up in the hosted portal.

Available options:

oidcazureoktagooglesamlworkos

allowed_domainsarray<string>

Email domains allowed to sign in, such as ["acme.com"]. Empty means any account the identity provider signs in.

activeboolean

Whether the connection can be used to sign in.

configuredboolean

Whether the identity provider settings are saved: issuer, client ID and client secret for OpenID Connect, the IdP metadata for SAML, the finished portal setup for Other providers. A connection created through the API is always configured.

issuerstring | null

Issuer of the identity provider, as its discovery document publishes it (for example https://acme.eu.auth0.com/). null for other connection types.

client_idstring | null

Client ID of the application in the identity provider. null for other connection types.

has_client_secretboolean

Whether a client secret is saved. The secret itself is never returned. Always false for other connection types.

redirect_uristring | null

Callback URL to register in the identity provider. null for other connection types.

created_atstring

Creation date, ISO 8601.

updated_atstring

Date of the last change, ISO 8601.

Endpoints

Get an SSO connection

/v2/sso-connections/{uuid}

POST

Create an SSO connection

/v2/sso-connections

PUT

Update an SSO connection

/v2/sso-connections/{uuid}

DELETE

Delete an SSO connection

/v2/sso-connections/{uuid}

Terraform

The Terraform provider manages OpenID Connect connections with the hyperping_statuspage_sso_connection resource (version 2.2.0 and later), and reads any connection, SAML included, with the data source of the same name.

← Delete a subscriber List SSO connections →