AWS Workload Identity
KnoxCall accepts AWS-issued OIDC tokens from EKS pods (IRSA) and other workloads withAWS_WEB_IDENTITY_TOKEN_FILE configured. STS workload identity for ECS / Lambda is supported via the same pattern.
1. Set up the IAM role + EKS service account (IRSA)
Existing AWS IAM setup — your cluster’s OIDC provider must be registered. See AWS docs. Once configured, your pod has these env vars automatically:AWS_WEB_IDENTITY_TOKEN_FILE(path to a file containing a signed JWT)AWS_ROLE_ARN
2. Configure the KnoxCall binding
Create the workload binding in the dashboard with Settings → API → Workload Identity → Connect workload, or call the admin API directly. The/admin/* routes are served on the admin host (admin.knoxcall.com / any knoxcall.com host) and 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.sts.amazonaws.com carries the role ARN in the arn claim.
3. Call KnoxCall
AWS_WEB_IDENTITY_TOKEN_FILE, exchanges the token for a KnoxCall access token, and uses it. No secrets stored.
Lambda / EC2 without IRSA — static client credentials
If you’re on Lambda or EC2 without IRSA, the SDK falls back to plainclient_credentials: the static KNOXCALL_CLIENT_ID + KNOXCALL_CLIENT_SECRET env vars. There is no IMDSv2 / EC2 instance-identity path — the SDK only reads AWS_WEB_IDENTITY_TOKEN_FILE for the OIDC flow and otherwise uses these env vars. Store them in AWS Secrets Manager or Lambda environment variables encrypted with a KMS key.
For Lambda with IRSA via container images, the IRSA env vars are set automatically by the Lambda runtime — same SDK works.
Troubleshooting
Could not detect KnoxCall credentials—AWS_WEB_IDENTITY_TOKEN_FILEis unset. Verify the pod’s service account is annotated witheks.amazonaws.com/role-arn.invalid_grant: no binding matched— decode the JWT (cat $AWS_WEB_IDENTITY_TOKEN_FILE | cut -d. -f2 | base64 -d) and compare itsarnclaim to your binding.