Organization Integrations

List the OAuth 2.0 BYOC integration presets supported by this deployment. Each preset carries the principal-binding declaration, documented scopes, admin setup instructions, and the redirect URI that must be registered on the admin's OAuth client.

Static bearer-token presets are intentionally excluded from this OAuth client-registration catalog because they do not require an OAuth client.

The catalog is a curated, code-defined list — only Perstack ships new presets; admins register credentials against an existing preset.

List BYOC OAuth 2.0 client registrations for the current organization. Only returns metadata — client secrets are never included in the response.

Register the admin-supplied OAuth 2.0 client credentials for a preset. The credentials are probed against the provider's token endpoint inside this request — registration is only persisted when the probe succeeds (invalid_grant response). A definitive rejection of the supplied config (invalid_client, redirect_uri_mismatch, unexpected response shape) returns 400 with the diagnostic and writes no row. A transient upstream outage returns 503, and an upstream rate-limit returns 429 with a Retry-After header — neither writes a row, so the caller can retry. The persisted row starts active and records successful verification through verifiedAt.

Subsequent operational drift (rotated credentials, revoked client) is detected via the manual re-verify endpoint POST /:integrationId/verify, which updates verifiedAt independently from lifecycle status and lets ops triage integration-side vs. connection-side failures.

Only one registration per (organization, presetKey) pair is allowed — re-registering the same preset must go through update or delete + create.

Fetch a single BYOC OAuth 2.0 client registration. Client secret is never returned.

Rotate the admin-supplied client ID and/or client secret. The new credentials are probed against the provider's token endpoint inside this request — the rotation is only persisted when the probe succeeds. A definitive probe rejection returns 400 with the diagnostic; a transient upstream outage returns 503 and an upstream rate-limit returns 429 with a Retry-After header. In every failure case the existing row is left untouched, so the integration cannot silently degrade into an unusable state.

The preset key is immutable — deleting and re-creating is the only way to switch preset.

Remove an organization's OAuth 2.0 client registration by its integration ID.

Probe the provider's token endpoint with the admin-registered credentials and a deliberately-bogus authorization code. A correctly-configured OAuth client fails with invalid_grant (credentials valid, code wrong) — that is the success signal. Any other failure maps to a specific diagnostic the UI can render.

A definitive verification result (success or a config-level failure) is persisted to verifiedAt and returned 200 with the outcome in the body. A transient upstream outage returns 503 / 429 with a Retry-After header and leaves the stored lifecycle status untouched, so a provider blip can never poison the integration's verification state.