SSOGEN API: Automation API, SCIM and OpenID Connect

SSOGEN offers three interfaces for other systems: the Automation API for scripts and pipelines, SCIM 2.0 for provisioning people and groups, and OpenID Connect discovery for applications that sign people in. This page says which one fits which job and describes the Automation API in full. It is for engineers who connect SSOGEN to their own tooling.

Which interface to use

Job	Interface	How the caller authenticates	Reference
A script or pipeline changes SSOGEN without a person present	Automation API, under /api	OAuth 2.0 access token from the client credentials grant	This page
An identity source creates, updates and deactivates people and groups in SSOGEN	SCIM 2.0, under /scim	Bearer provisioning token	SCIM reference
An application signs people in with SSOGEN	OpenID Connect, configured from /.well-known/openid-configuration	The application’s client ID and its secret or key	Register an OpenID Connect application
Another system reacts to what happens in SSOGEN	Webhooks (SSOGEN calls you)	A signature on every delivery	Webhooks

The Admin Console calls its own interface under /admin/api with the administrator’s console session. That interface serves the console. It is not a public integration surface, so scripts and products use the interfaces in the table above.

The Automation API at a glance

Item	Value
Base address	Your SSOGEN address followed by /api, for example https://sso.acme.example/api
Caller	An automation client: a service application registered in SSOGEN
Credential	Authorization: Bearer <access token> on every call
Token	Issued by /oauth2/token with grant_type=client_credentials, the resource https://sso.acme.example/api and the scope of the operation
Organization	Taken from the registered client, never from the request body
Browser cookies	Ignored on every Automation API call
Answers	JSON, Cache-Control: no-store, an X-Correlation-ID header on every answer

Operations

Method and path	What it does	Scope
PUT /api/gateway/certificates/{certificateId}	Replaces an existing App Proxy TLS certificate with a renewed chain and its private key	gateway-certificates

The body carries chain_pem (the leaf certificate first, then each issuer) and private_key_pem (the leaf’s PKCS#8 key), both PEM. The answer holds certificate_id, version, chain_sha256, not_after and changed.

• Replace only. The call rotates a certificate that already exists in the console; it never creates one.
• Safe to retry. A chain identical to the current one changes nothing and answers "changed": false.
• Same checks as the console. A wrong key, an expired certificate or a name no longer covered is refused, and nothing is stored.
• Key never returned. The private key is never returned, logged or audited.
• Rate limited. At most 10 calls a minute per client.
• Audited. Every rotation is recorded in the audit log with the automation client as the actor.

Register an automation client

A Super admin registers the client, because only a Super admin can grant an automation scope.

1. Open Applications, then OpenID Connect, and select Register service.
2. Under Access, set Audiences to your SSOGEN address followed by /api and Scopes to gateway-certificates.
3. Under Authentication, choose Private key JWT (recommended) and paste the tool’s public keys, or choose Client secret.
4. Select Register. With a client secret, copy it when it is shown; SSOGEN does not show it again.

The full walkthrough, with screenshots and the certificate screen’s Automation panel, is in Publish an internal app with the App Proxy, section 10.2.

Call the API

Get a token with the client credentials grant. Example with a client secret:

curl -s -X POST https://sso.acme.example/oauth2/token \
  -u "acme-certificate-manager:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  --data-urlencode resource=https://sso.acme.example/api \
  -d scope=gateway-certificates

Then push the renewed certificate:

jq -n --rawfile c chain.pem --rawfile k key.pem \
  '{chain_pem: $c, private_key_pem: $k}' > renewal.json
curl --request PUT "https://sso.acme.example/api/gateway/certificates/gcert_xxxxxxxx" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data @renewal.json

Errors

A refused call answers with the HTTP status and one JSON envelope:

{
  "error": {
    "code": "SSO-CERT-400-EXPIRED",
    "message": "The certificate has expired or expires within a day.",
    "correlation_id": "0f8b2c1e-7a4d-4e55-9c1b-3d2a6f7e8b90"
  }
}

Status	Meaning
400	The request or the certificate failed a check
401	No valid access token
403	The client does not hold the scope for this operation
404	No certificate with this ID
409	The new certificate does not cover a hostname that uses this one
429	More than 10 calls in a minute from this client

Enter the correlation_id in the audit log’s Correlation id filter to see the recorded outcome. Every code is listed in Error codes.

Protect the automation client

The client can replace certificates

Anyone who holds the client’s secret or private key can replace your App Proxy certificates. If the secret leaks, disable the client first, then replace the secret. Re-enabling a disabled automation client needs a Super admin.

Related guides

• SCIM reference for provisioning people and groups.
• Register an OpenID Connect application for discovery and service applications.
• Webhooks for events sent from SSOGEN.
• Audit log for the record of every call.