POST/v2/sso-connections

Create an SSO connection

Creates an OpenID Connect connection for private status pages. Hyperping checks the identity provider before saving: a configuration it refuses creates nothing and is not billed.

Request

Bodyapplication/json

namestringrequired

Name of the connection, shown in the dashboard. At most 255 characters.

issuerstringrequired

Issuer URL of the identity provider: the address before /.well-known/openid-configuration, such as https://acme.eu.auth0.com/. A bare domain (acme.eu.auth0.com) also works. It must use https:// and reach a public address. Hyperping saves the issuer the discovery document publishes, so the response can spell it differently from the request.

client_idstringrequired

Client ID of the web application created in the identity provider. No spaces, at most 255 characters.

client_secretstringrequired

Client secret of the application. Stored encrypted and never returned by the API.

allowed_domainsarray<string>optional

Email domains allowed to sign in, such as ["acme.com"]: a visitor's email must be at one of them. Empty lets in any account the identity provider signs in for the application. At most 100 domains, stored as sent. Default: []

providerstringoptional

Only oidc is accepted. SAML connections are created in the dashboard. Default: oidc

Before you call it

Create a web application with a client secret in your identity provider, and register https://api.hyperping.io/v1/auth/sso/oidc/callback as an allowed callback URL (https://api.eu.hyperping.io/v1/auth/sso/oidc/callback for EU accounts). The response returns this URL as redirect_uri. The status page SSO guide and the Auth0 guide walk through the provider side.

What Hyperping checks

Before anything is saved, Hyperping fetches the discovery document of the issuer, then asks the identity provider whether it accepts the client ID and secret. If either check fails, the request fails with 400: the body names the failed check in code and lists every check in checks. When the identity provider's answer does not say either way, the connection is saved: run Test connection on its card in the dashboard to try a real sign-in.

Billing

The connection is billed like one created in the dashboard, from the moment it is created: $49 per month (€49 on EUR billing), or included on plans that include SSO connections. The project's owner needs a payment method on file. See pricing.

Response

Returns 201 with the new connection object. Set its uuid as authentication.sso_connection_uuid when you create or update a status page.

Errors

Error responses

400invalid body

A required field is missing or a value is not valid, such as name is required or allowed_domains: "acme" is not a domain (example: acme.com)

400identity provider refused

The discovery document could not be read, or the identity provider refused the client ID and secret. code says why, for example discovery_not_found, insecure_url, unreachable, client_refused or client_grant_not_allowed

400provider not supported

provider is not oidc

400No billing account found

The project's owner has no payment method and no plan that includes SSO connections

403read-only key

The API key has read-only permissions

RequestcURL

curl -X POST https://api.hyperping.io/v2/sso-connections \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme employees",
    "issuer": "https://acme.eu.auth0.com/",
    "client_id": "x8Qm2LkP0vZr7TnY4bWc",
    "client_secret": "YOUR_CLIENT_SECRET",
    "allowed_domains": ["acme.com"]
  }'

201 CreatedJSON

{
  "message": "SSO connection created",
  "connection": {
    "uuid": "sso_kQwPzRtLmYbN4v",
    "name": "Acme employees",
    "provider": "oidc",
    "allowed_domains": ["acme.com"],
    "active": true,
    "configured": true,
    "issuer": "https://acme.eu.auth0.com/",
    "client_id": "x8Qm2LkP0vZr7TnY4bWc",
    "has_client_secret": true,
    "redirect_uri": "https://api.hyperping.io/v1/auth/sso/oidc/callback",
    "created_at": "2026-10-15T09:12:44.000Z",
    "updated_at": "2026-10-15T09:12:45.000Z"
  }
}

400 Bad RequestJSON

{
  "error": "The identity provider refused this client ID and secret (Unauthorized).",
  "code": "client_refused",
  "checks": [
    {
      "step": "discovery",
      "ok": true,
      "message": "Found the identity provider: https://acme.eu.auth0.com/"
    },
    {
      "step": "client",
      "ok": false,
      "message": "The identity provider refused this client ID and secret (Unauthorized)."
    }
  ]
}

← Get an SSO connection Update an SSO connection →