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. TheVERCEL_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.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
previewvsproductionenvironments — preview deployments shouldn’t be able to mint production tokens. - Limit
allowed_scopesto what the function actually needs.
Troubleshooting
VERCEL_OIDC_TOKENnot set — OIDC isn’t enabled on the project, or you’re running locally (vercel dev). For local dev, setKNOXCALL_CLIENT_ID+KNOXCALL_CLIENT_SECRETdirectly.invalid_grant: no binding matched— preview deployments carryenvironment: "preview"; ensure your bindings differentiate.