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.
• The signature uses an asymmetric algorithm (RS256 for Clerk; RS256 or ES256 for Supabase) and verifies against your IdP's public keys.

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.

Token helper pattern

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. This is the same mechanism the Swirls CLI uses internally.

The token grants access scoped to the organization that registered the identity provider.

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.

Next steps

• API reference: all available API namespaces and methods.
• SDK reference: typed TypeScript client.
• Swirls Cloud: managed runtime and Portal.