OIDC Federation

OIDC Federation lets your workload authenticate to Swirls using a JWT issued by your own identity provider. Your workload exchanges that JWT at the Swirls token endpoint and receives a short-lived Swirls access token. Use that token to call the Swirls API.

No long-lived Swirls API keys to store or rotate. Your organization keeps full control at its own identity provider.

How it works

Your workload requests a JWT from your identity provider (Clerk or Supabase). It presents that JWT to the Swirls token endpoint. Swirls verifies the JWT against the registered provider configuration and returns a short-lived access token. Your workload uses that access token to call the Swirls API, then discards it. When the token expires, repeat the exchange.

Configure a provider

{
  "aud": "swirls:aud:9fK2x7..."
}

Exchange a JWT for a Swirls access token

Swirls implements RFC 8693 OAuth 2.0 Token Exchange.

Endpoint: POST https://auth.swirls.ai/oauth2/token

Content-Type: application/x-www-form-urlencoded

No client ID or client secret. The subject token authenticates the request.

JWT requirements

Before exchanging, verify your JWT satisfies all of these:

• iss matches the issuer shown in the Portal for your registered provider.
• aud contains the Swirls audience (swirls:aud:...).
• The subject claim (default sub) is non-empty.
• exp is in the future, and nbf (if present) is not.
• The signature uses an asymmetric algorithm (RS256 for Clerk; RS256 or ES256 for Supabase) and verifies against your IdP's public keys. Symmetric algorithms are rejected.

Example

curl -s -X POST https://auth.swirls.ai/oauth2/token \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token=$YOUR_IDP_JWT" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:jwt"

Successful response

HTTP 200:

{
  "access_token": "...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 900
}

The access_token is an opaque bearer token. Do not parse or inspect it. Present it directly in API requests.

Tokens are short-lived (approximately 15 minutes). There is no refresh token. When the token expires, mint a fresh JWT from your IdP and exchange again.

SDK helper

If you call Swirls through the TypeScript SDK, skip the manual exchange. createFederatedTokenSource from @swirls/sdk/auth performs the exchange, caches the token, and re-exchanges before expiry:

import { Swirls } from "@swirls/sdk/client"
import { createFederatedTokenSource } from "@swirls/sdk/auth"

const swirls = new Swirls({
  apiKey: createFederatedTokenSource({
    getSubjectToken: () => mintIdpJwtForUser(),
  }),
})

Token helper pattern

Calling the API directly instead? Wrap the exchange in a helper that caches the token until near expiry:

let cached: { token: string; expiresAt: number } | null = null

async function getSwirlsToken(idpJwt: string): Promise<string> {
  const now = Date.now()
  if (cached && cached.expiresAt - now > 30_000) {
    return cached.token
  }

  const res = await fetch("https://auth.swirls.ai/oauth2/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
      subject_token: idpJwt,
      subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
    }),
  })

  if (!res.ok) {
    const err = await res.json()
    throw new Error(`Token exchange failed: ${err.error}`)
  }

  const data = await res.json()
  cached = {
    token: data.access_token,
    expiresAt: now + data.expires_in * 1000,
  }

  return cached.token
}

This follows the same pattern as AWS and GCP workload credential helpers: exchange once, cache until near expiry, then re-exchange.

Discovery

Swirls publishes OAuth 2.0 authorization server metadata at:

GET https://auth.swirls.ai/.well-known/oauth-authorization-server

This returns an RFC 8414 metadata document listing the token endpoint and the supported token-exchange grant. Standard OAuth client libraries can discover the endpoint from this URL.

Error reference

Errors are returned as standard OAuth JSON error objects. Error details are intentionally opaque to avoid leaking information about token validation.

Authenticate to Swirls endpoints

Present the access token as a bearer token in every API request:

Authorization: Bearer <access_token>

The Swirls API base URL is https://swirls.ai/api.

The token grants access scoped to the organization that registered the identity provider. A federated principal is not an organization member; it authenticates as itself, confined to that organization's data.

Example

curl -s https://swirls.ai/api/<endpoint> \
  -H "Authorization: Bearer $SWIRLS_ACCESS_TOKEN"

See the API reference for available endpoints and their paths.

Handling token expiry

The token expires after approximately 15 minutes. API requests with an expired token receive a 401 Unauthorized response.

On a 401, mint a fresh JWT from your identity provider and exchange it for a new access token. The token helper pattern above handles this automatically when you call getSwirlsToken before each request.

Map identity claims to access roles

Federated principals can be scoped to specific agents using the access control blocks in your .swirls files. The verified claims from the JWT your principal exchanged become their access attributes. role blocks match on those claims, and policy grants decide which agents each role reaches, with workflow and tool narrowing declared per grant.

Your identity provider never assigns a Swirls role. It only asserts facts, and your deployed role blocks decide which facts to trust. The claim keys named in match rules are the only claims the policy engine reads.

Declare roles that match your claims

Put the facts in the JWT, then match on them:

role finance {
  match {
    department: "finance"
  }
}

role support_lead {
  match {
    groups: [ "support-leads" ]
  }
}

policy {
  allow finance -> agent accountant {
    workflows: [ brex, quickbooks ]
  }
  allow support_lead -> agent support
}

Declaring any policy grant flips the project to deny by default: a federated principal whose claims match no granting role cannot run the deployment.

Add the claims at your identity provider

{
  "aud": "swirls:aud:9fK2x7...",
  "department": "{{user.public_metadata.department}}",
  "groups": "{{user.public_metadata.groups}}"
}

claims := jsonb_set(claims, '{department}', to_jsonb(user_department));

How the claims are evaluated

• Claims are captured at each token exchange, after signature, issuer, and audience verification. Access decisions reflect the most recent exchange, so a claim change at your identity provider takes effect the next time the principal exchanges a token.
• A scalar claim is an equality test, a list claim is a membership test, and multiple conditions in one match block must all hold. See access control for the full semantics.
• org_role applies to Swirls users only. Federated principals are not organization members, so match on claims you control at your identity provider instead.

Next steps

• Access control: role and policy blocks, match semantics, and enforcement.
• API reference: all available API namespaces and methods.
• SDK reference: typed TypeScript client.
• Swirls Cloud: managed runtime and Portal.