How Identities Authenticate
Willow has two kinds of runtime identity, and they authenticate by fundamentally different mechanisms. Understanding the split matters when you build against the gateway or run an internal MCP server behind it, because it determines what credential reaches your server.
There are two separate questions:
- The front door: how does an identity authenticate to the Willow gateway?
- Downstream: when a call is proxied to an internal MCP server, what credential does that server receive?
Users and machine users
Users are people. They sign in interactively and inherit access from their groups.
Machine users are API accounts for bots, scripts, and automations. They have no interactive session.
The front door
| Identity | How it authenticates to the gateway |
|---|---|
| User | Through the identity provider: SSO (Okta, Keycloak) or Google / GitHub login |
| Machine user | With its access key and secret, sent as Bearer <access_key>:<secret> |
A machine user does not use the SSO provider at all to reach the gateway. Its access-key authentication is independent of SSO and works even when no SSO provider is configured. This is why the Machine Users page describes them as bypassing the interactive authentication flow.
Downstream: reaching an internal MCP server
When an MCP server is configured with Proxy Passthrough, Willow forwards a credential to that server on each call. What it forwards depends on the caller:
| Caller | What Willow forwards to the passthrough server |
|---|---|
| User | The user's own SSO provider token (see JWT Passthrough) |
| Machine user | A token minted from the machine user's client credentials |
For a user, there is a live SSO session, so the user's token can be passed through directly. A machine user has no interactive session and therefore no SSO token, so Willow performs a client-credentials grant against the same identity provider using the machine user's configured client, and forwards the resulting token.
The result is the same shape of token reaching the MCP server, obtained through a different OAuth grant suited to whether the caller is interactive.
Why this matters when you build
- If you call the gateway from a script, you are a machine user: authenticate with
access_key:secret. See Programmatic Gateway Access. - If you run an internal MCP server behind Willow, the token it receives depends on the server's auth mode and the caller type. See Build an MCP Server Behind Willow and the authentication types reference.
- For human users, an internal server can also authenticate them directly, either through its own OAuth flow or with per-user API keys. See Build an OAuth-Protected MCP Server and Accept Per-User API Keys, or the hands-on OAuth and API-key tutorials.