instance

Configure an OIDC federation issuer.

Changed on

The issuer string is stored and matched BYTE-EXACT, with no canonicalization step. OpenID Connect defines iss as case-sensitive, so any normalization that folds case, resolves a URL or strips a trailing slash can merge two distinct external issuers into one configuration — and the uniqueness constraint would enforce the merge rather than catch it.

post/api/v1/instance/federation-issuers

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/instance/federation-issuers
  • Auth: HTTP bearer

Request body

issuerstring required

The byte-exact iss, https:// only. Discovery and JWKS are fetched from this URL, so an http issuer would rest the instance's whole federation trust on whoever holds the network path.

issuer_type'kubernetes' | 'forgejo' | 'github-actions' required

The federation issuer's platform. It is DECLARED rather than inferred from the issuer URL, because the per-platform binding rules differ — a Forgejo or GitHub Actions binding MUST pin event_name, a Kubernetes one has no such claim — and inferring the type from a URL would let renaming a deployment change the security rules that apply to it.

jwks_mode'discovery' | 'static' required

Where the issuer's signing keys come from. discovery is the default: keys are fetched and cached with a bounded staleness window. static is the configured alternative for air-gapped installations and for deployments whose issuer discovery endpoint this instance cannot reach — deliberately not the default, because a static-only installation breaks silently on the day someone rotates the issuer's keys.

ca_bundle_pemstring

PEM CA certificates for discovery and JWKS HTTPS requests, including redirects. Replaces system roots for this issuer only. Nonempty values are refused in static mode. On update, omission preserves the current bundle in discovery mode; an empty string clears it. Static mode clears the bundle. This field is write-only; reads report ca_bundle_configured.

static_jwksstring

The JWKS document, required under static mode and refused under discovery. The pairing is total: a document stored but unused is a key set nobody rotates.

refused_audiencesstring[] required

Response

The configured issuer.

idstring required

A prefixed UUIDv7, e.g. org_0198….

issuerstring required

The byte-exact iss. Nothing folds case, resolves the URL or strips a trailing slash: OpenID Connect defines iss as case-sensitive, so any normalization could merge two distinct external issuers into one configuration.

issuer_type'kubernetes' | 'forgejo' | 'github-actions' required

The federation issuer's platform. It is DECLARED rather than inferred from the issuer URL, because the per-platform binding rules differ — a Forgejo or GitHub Actions binding MUST pin event_name, a Kubernetes one has no such claim — and inferring the type from a URL would let renaming a deployment change the security rules that apply to it.

jwks_mode'discovery' | 'static' required

Where the issuer's signing keys come from. discovery is the default: keys are fetched and cached with a bounded staleness window. static is the configured alternative for air-gapped installations and for deployments whose issuer discovery endpoint this instance cannot reach — deliberately not the default, because a static-only installation breaks silently on the day someone rotates the issuer's keys.

refused_audiencesstring[] required

The issuer's DEFAULT audiences, which no binding may name and which no token may carry. At least one is required: a Kubernetes API-server audience is whatever that cluster was configured with and is not derivable, so an empty list would silently accept the audience that must be refused.

created_atstring date-time required

RFC 3339 UTC, microsecond precision.

created_bystring required

A prefixed UUIDv7, e.g. org_0198….

updated_atstring date-time

RFC 3339 UTC, microsecond precision.

updated_bystring

A prefixed UUIDv7, e.g. org_0198….

ca_bundle_configuredboolean required

Whether discovery uses an issuer-specific CA bundle instead of system roots.

live_bindingsinteger required

How many bindings name this issuer, LIVE OR HISTORICAL, so an operator sees the blast radius before attempting a delete — which is refused while any remain. Revoked bindings count: erasing the issuer a past binding trusted erases what it trusted, and the foreign key would refuse the delete anyway with a driver message instead of a reason.

Changes

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status