Azure Workload Identity
Azure workloads with a system-assigned or user-assigned Managed Identity get a local metadata endpoint that issues short-lived tokens. KnoxCall accepts these via RFC 8693.1. Enable Managed Identity on your resource
Azure portal: Identity → System assigned: On (or attach a user-assigned identity). This sets the env vars on every request:IDENTITY_ENDPOINT— local metadata URLIDENTITY_HEADER— header value the metadata service requires
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 API is authenticated by your dashboard session JWT plus an X-Tenant-ID header (it is not the API-key data plane on 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.oid claim). You can also lock tid (tenant) or appid for tighter control.
3. Call KnoxCall
$IDENTITY_ENDPOINT?resource=knoxcall:api with the X-IDENTITY-HEADER, gets the JWT, exchanges it for a KnoxCall token.
Troubleshooting
Could not detect KnoxCall credentials— Managed Identity isn’t enabled or env vars aren’t propagated. Check the resource’s Identity blade.invalid_target—resourceparam in the metadata call must be exactlyknoxcall:api; we set this automatically.invalid_grant: no binding matched— verify theoidof your Managed Identity (runaz identity show --ids <resource-id> --query principalId) matches the binding.