Credentials

Each provider gets a credential source. The gateway calls it per request, after the policy allows the call, and adds the result to the upstream request. The agent only ever holds a session token.

Static tokenCopy Anchor Link

gmail({ credentials: staticToken({ token: process.env.GMAIL_ACCESS_TOKEN! }) });

Refreshing OAuth tokenCopy Anchor Link

Access tokens are fetched with the refresh token, cached until shortly before they expire, and never leave the gateway. refreshToken can be resolved per user from the session:

import { oauth2Refresh } from "@waterlock/gateway";

gmail({
  credentials: oauth2Refresh({
    tokenUrl: "https://oauth2.googleapis.com/token",
    clientId,
    clientSecret,
    refreshToken: (session) => lookupRefreshToken(session.onBehalfOf),
  }),
});

How it's sentCopy Anchor Link

By default the credential goes out as Authorization: Bearer <token>. A provider can change that: Linear's auth: "apiKey" sends a personal API key in the Authorization header without Bearer, as Linear expects for API keys. If the credential source fails, the call gets 502 upstream_auth and nothing is forwarded.