Upstream Providers | AuthOS Docs | Auth Operating System API and SDK Guides

Upstream providers connect an organization to an external identity provider. Every endpoint requires an authenticated member with the integrations:manage capability. Provider lookup, update, and deletion are scoped to the organization in the URL; an identifier owned by another tenant returns 404.

The API never returns client secrets. OIDC and OAuth 2.0 providers require a non-empty confidential client secret. Provider URLs must be absolute HTTPS URLs and pass AuthOS outbound-address validation.

`GET /api/organizations/{org_slug}/upstream-providers`

Lists the organization’s providers.

`GET /api/organizations/{org_slug}/upstream-providers/{provider_id}`

Returns one provider by its AuthOS provider ID.

`POST /api/organizations/{org_slug}/upstream-providers`

Creates a provider. The request accepts:

connection_id, name, provider_type, and client_id
client_secret for OIDC and OAuth 2.0
issuer, authorization_url, token_url, userinfo_url, or discovery_url, as required by the provider
optional scopes, metadata, and enabled

provider_type must be oidc, oauth2, or saml. OIDC and OAuth 2.0 need either discovery_url or all three explicit authorization, token, and user-info URLs. SAML requires authorization_url.

connection_id, name, and client_id must be non-empty and are limited to 128, 200, and 512 bytes respectively. scopes is limited to 2,048 bytes.

`PATCH /api/organizations/{org_slug}/upstream-providers/{provider_id}`

Updates name and/or enabled. Unknown fields are rejected. To rotate a credential or change protocol configuration, delete and recreate the provider.

`DELETE /api/organizations/{org_slug}/upstream-providers/{provider_id}`

Deletes the provider and returns { "success": true }.

Response shape

Create, get, and update return the same non-secret shape:

{
  "id": "provider-uuid",
  "connection_id": "workforce-idp",
  "name": "Workforce identity",
  "provider_type": "oidc",
  "client_id": "authos-client",
  "issuer": "https://idp.example.com",
  "authorization_url": "https://idp.example.com/authorize",
  "enabled": true,
  "created_at": "2026-08-02T12:00:00Z"
}

Nullable URL fields are serialized as null. Configuration fields such as client secrets, token URLs, user-info URLs, discovery URLs, scopes, metadata, organization IDs, and update timestamps are deliberately omitted.