Skip to main content

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​

OptionIdentity verified byUse it when
Auth exchangeYour identity providerThe user is already signed in to your system through Okta or Keycloak, and you hold their token.
Enterprise-managed authenticationYour identity providerThe client is Claude, and your organization signs in to both Claude and Willow with Okta.
ImpersonationYour applicationYour server authenticates the user and supplies their email to Willow.
OAuthThe user's sign-inThe client supports OAuth and can store access and refresh tokens.
OTTThe user's sign-inThe client uses a session token without OAuth client registration or refresh-token storage.
Machine users and background agentsThe automation holds its own Willow credentialA 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 userBackground agent
PurposeAuthenticate an external service or scriptRun an agent configured in Willow
Tool accessGroup membershipAssigned capabilities
Agent configurationManaged by your applicationWillow 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.

Require a verified initiator

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 with x-user-email, or
  • an auth-exchange IdP JWT (Okta/Keycloak), sent with x-user-auth-exchange: true and your organization API token in x-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.

Run as the initiator uses the triggering person's GitHub account

Token lifetime and rotation​

Machine-user secrets are long-lived credentials that you rotate in Willow. Background agents can have several tokens:

Token kindEffect of deploying or syncing the agent
PlatformReplaced with a new token for the runtime. Its previous value stops working. Platform tokens cannot fire API triggers.
ManualRemains valid. Use a named manual token for an outside caller, such as an MCP client or API trigger.
LegacyRemains 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.