How Agents Authenticate to Willow
Clients authenticate to the Willow gateway using one of the methods below. A user's groups determine their access to resources. Background agents use their assigned capabilities.
For credentials used to call upstream services, see Authentication: Connector vs Proxy Modes. Background agents also choose an integration account for each MCP server.
The options
| Option | Identity verified by | Use it when |
|---|---|---|
| Auth exchange | Your identity provider | The user is already signed in to your system through Okta or Keycloak, and you hold their token. |
| Enterprise-managed authentication | Your identity provider | The client is Claude, and your organization signs in to both Claude and Willow with Okta. |
| Impersonation | Your application | Your server authenticates the user and supplies their email to Willow. |
| OAuth | The user's sign-in | The client supports OAuth and can store access and refresh tokens. |
| OTT | The user's sign-in | The client uses a session token without OAuth client registration or refresh-token storage. |
| Machine users and background agents | The automation holds its own Willow credential | A service authenticates as itself. A background agent can separately use the triggering person's account for an integration. |
Auth exchange
Send the user's Okta or Keycloak JWT to the gateway with x-auth-exchange: true. Willow verifies it against your JWKS endpoint and resolves the existing Willow user by email.
Include an organization API token that authorizes your application to perform auth exchanges. Keep this API token on your server. The user must already exist in Willow.
Read more: Auth Exchange
Enterprise-managed authentication
When Claude and Willow both use Okta, Claude can exchange an Okta assertion for a Willow access token without another sign-in prompt. Okta app assignments and policies control access.
Willow verifies the assertion against your Okta signing keys and matches an existing user by SCIM identity or email. Tokens last at most one hour and cannot be refreshed.
Read more: Enterprise-Managed Authentication
Impersonation
Send an API token with the run:impersonate scope and an x-user-email header. Willow runs the call as the specified user. Your application is responsible for authenticating that user.
The token can act as any user in the organization, including admins. Keep it server-side and use a separate token for each application. The all scope and legacy unscoped tokens also permit impersonation.
If your application has an Okta or Keycloak token for the user, use auth exchange.
Read more: API Tokens
OAuth
Willow provides an OAuth 2.0 / OpenID Connect authorization server. The client registers, sends the user to /authorize, and exchanges the authorization code for an access token. The user signs in through your identity provider, using its MFA and access policies.
Cursor, VS Code, Claude, and ChatGPT support this flow with the Willow gateway URL. An OAuth client stores its registration, access token, and refresh token and handles the redirect. Token lifetime defaults to 24 hours and is configurable.
Use PKCE (S256) to protect the authorization code. Allow only authenticated clients in security settings restricts connections to configured AI tools.
Read more: OAuth Authorization Server
OTT
Your application generates a token and requests a sign-in URL from Willow. The user opens the URL and signs in through SSO. Willow binds the token to that user, and your application polls for completion. Subsequent calls use Authorization: <userAccessKey>:<OTT>.
OTT does not require OAuth client registration, a refresh token, or a redirect endpoint. The application can keep the credential in memory and repeat sign-in after a restart. The session token is reusable and lasts 24 hours by default.
Send the sign-in URL privately to the intended user. The token is bound to the person who completes sign-in.
Read more: User Session Authentication
Machine users and background agents
Machine users and background agents authenticate to the gateway with Authorization: Bearer <access_key>:<secret>.
| Machine user | Background agent | |
|---|---|---|
| Purpose | Authenticate an external service or script | Run an agent configured in Willow |
| Tool access | Group membership | Assigned capabilities |
| Agent configuration | Managed by your application | Willow manages the prompt, skills, triggers, sessions, and runtime deployment |
The integration account
On a background agent's Tools tab, each MCP server has its own authentication selection. Run as the initiator uses the triggering person's connection to a per-user-auth server. Slack identifies that person automatically. API triggers and direct MCP/API connections supply x-user-email or x-user-id. A schedule has no interacting person, so choose a connected account suitable for the scheduled job.
When Require a verified initiator is on for an agent (set it per organization or per agent in Background Agent Settings), API triggers and direct MCP/API connections must prove who the initiator is with an x-user-token header rather than a bare x-user-email or x-user-id. The token is any of:
- the initiator's own OAuth access token,
- their OTT user-session token,
- an impersonation API token (
run:impersonate), sent together withx-user-email, or - an auth-exchange IdP JWT (Okta/Keycloak), sent with
x-user-auth-exchange: trueand your organization API token inx-api-key. Willow verifies the JWT against your JWKS and acts as the user it names.
Willow verifies the token and acts as that user; it never acts on a name the caller only asserted. Slack and other Willow-verified channels are unaffected because they identify the person themselves.
See Give an agent access to tools for configuration steps.
Token lifetime and rotation
Machine-user secrets are long-lived credentials that you rotate in Willow. Background agents can have several tokens:
| Token kind | Effect of deploying or syncing the agent |
|---|---|
| Platform | Replaced with a new token for the runtime. Its previous value stops working. Platform tokens cannot fire API triggers. |
| Manual | Remains valid. Use a named manual token for an outside caller, such as an MCP client or API trigger. |
| Legacy | Remains valid and works like a manual token. |
Creating a manual token does not replace existing tokens. Recreating or revoking a token invalidates that token's previous value; update the callers that use it. See Background agent credentials.
Read more: Machine Users · Background Agents · Programmatic Gateway Access
Worked example
Authenticate a Slack Agent shows the requests for a Slack bot using impersonation, OTT sign-in, or a background-agent credential.
Related
- How Identities Authenticate — what credential reaches an internal MCP server behind the gateway
- Identity and Permissions — how access resolves once the identity is settled
- Connect Your AI Client — the end-user path