Identity Federation
SDK reference for identity federation — Configure project-scoped OIDC federation, reusable organization providers, and explicit inheritance.
Configure project-scoped OIDC federation, reusable organization providers, and explicit inheritance.
These management methods require an organization owner/admin session credential. Federated workload credentials cannot configure providers. Organization defaults must be explicitly inherited into each project before exchanging tokens; each binding receives its own audience. Inheritance copies settings and links removal to the source. To change the same issuer between inheritance and independent configuration, remove its project binding and register or inherit a replacement, then update the JWT audience. There is no automatic fallback. See OIDC Federation for setup and migration.
inherit
Inherit an organization identity provider in a project, provisioning a unique project audience. Requires an organization owner or admin.
POST
Usage:
const binding = await swirls.client.idp.inherit({
projectId,
id: organizationProviderId,
})
// Configure this project's IdP JWT template with binding.audience.Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Target project UUID in the active organization. |
id | string | Yes | Organization default provider ID to inherit; project binding IDs are rejected. |
Output:
| Field | Type | Description |
|---|---|---|
projectId | string | null | Owning project UUID; null for an organization default. |
inheritedFromId | string | null | Source organization provider ID for an inherited binding; null for independent registrations. |
id | string | |
provider | string | |
instanceIdentifier | string | |
issuer | string | |
audience | string | Unique audience for this registration. Only project binding audiences support token exchange. |
subjectClaim | string | |
status | "pending" | "active" | |
createdAt | string |
list
List the OIDC identity providers registered for a project, or the active organization when projectId is omitted. Requires an organization owner or admin.
GET
Usage:
const projectProviders = await swirls.client.idp.list({ projectId })
const organizationDefaults = await swirls.client.idp.list({})Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | No | Target project UUID in the active organization. Omit to manage organization defaults. |
Output:
| Field | Type | Description |
|---|---|---|
providers | object[] |
register
Register an identity provider for a project, or an organization default when projectId is omitted. Requires an organization owner or admin. Project bindings activate on the first successful token exchange.
POST
Usage:
const binding = await swirls.client.idp.register({
projectId,
provider: 'clerk',
instanceIdentifier: 'clerk.acme.com',
})
// Configure this project's IdP JWT template with binding.audience.
// Omit projectId to register a reusable organization default instead.Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | No | Target project UUID in the active organization. Omit to manage organization defaults. |
provider | "clerk" | "supabase" | Yes | |
instanceIdentifier | string | Yes | Clerk Frontend API domain or Supabase project reference, without a URL scheme. |
subjectClaim | string | No | JWT claim carrying the principal identity. Defaults to sub. |
Output:
| Field | Type | Description |
|---|---|---|
projectId | string | null | Owning project UUID; null for an organization default. |
inheritedFromId | string | null | Source organization provider ID for an inherited binding; null for independent registrations. |
id | string | |
provider | string | |
instanceIdentifier | string | |
issuer | string | |
audience | string | Unique audience for this registration. Only project binding audiences support token exchange. |
subjectClaim | string | |
status | "pending" | "active" | |
createdAt | string |
remove
Remove an identity provider from a project, or the active organization when projectId is omitted. Removing an organization default revokes all inherited bindings; removing a project binding leaves its default intact. Issued credentials fail on their next verification. Requires an organization owner or admin.
POST
Usage:
await swirls.client.idp.remove({ projectId, id: projectProviderId })
// Removing a default also revokes all inherited project bindings:
await swirls.client.idp.remove({ id: organizationProviderId })Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | No | Target project UUID in the active organization. Omit to manage organization defaults. |
id | string | Yes | Provider ID in the exact project or organization scope being removed. |
Output:
| Field | Type | Description |
|---|---|---|
removed | true |