Skip to main content

Vercel Workload Identity

Vercel issues per-deployment OIDC tokens (VERCEL_OIDC_TOKEN) to every function. KnoxCall accepts them via RFC 8693 token exchange.

1. Enable OIDC for your Vercel project

Vercel project → Settings → OIDC Federation → Enable. The VERCEL_OIDC_TOKEN env var is then injected into every deployment.

2. Configure the trust binding

Create the binding in the dashboard with Settings → API → Workload Identity → Connect workload, or call the admin API on the admin host (admin.knoxcall.com). The /admin/* routes are authenticated by your logged-in admin/owner session — a session JWT plus the X-Tenant-ID header — not an API key against api.knoxcall.com.
Creating a binding requires a recent step-up verification with a second factor (passkey, security key or authenticator-app code; an emailed code does not count), made within the last 5 minutes for this action: it must carry "action_scope": "oauth.client". A binding is a trust that lets an external workload mint tenant tokens, so it carries the same bar as creating an OAuth client. A curl carrying only a session JWT answers 403 with "requires_step_up": true, "action_scope": "oauth.client" and "allowed_methods": ["passkey", "2fa"]. On the same session, first call POST /auth/2fa/verify-step-up with {"totp_code": "<code>", "action_scope": "oauth.client"}, or complete a WebAuthn step-up in a browser with the same action_scope (POST /auth/passkey/verify-step-up for a passkey, or POST /auth/2fa/webauthn/step-up-options then POST /auth/2fa/webauthn/verify-step-up for a security key), then replay the request inside the 5-minute window. A verification made for a different action, such as one a Dashboard prompt raised, carries that action’s scope and does not satisfy this gate. Each verification is single-use, so a retried request needs a fresh one. Listing and revoking bindings need no verification: containment must never be gated.
Lock to your Vercel org (owner), project, and environment. The token also carries aud, iss, iat, exp, plus deployment metadata (deployment_id, git_commit_sha).

3. Call KnoxCall from your function

Recommendations

  • Use separate bindings for preview vs production environments — preview deployments shouldn’t be able to mint production tokens.
  • Limit allowed_scopes to what the function actually needs.

Troubleshooting

  • VERCEL_OIDC_TOKEN not set — OIDC isn’t enabled on the project, or you’re running locally (vercel dev). For local dev, set KNOXCALL_CLIENT_ID + KNOXCALL_CLIENT_SECRET directly.
  • invalid_grant: no binding matched — preview deployments carry environment: "preview"; ensure your bindings differentiate.