Skip to main content

​
OAuth

Sanvex shares routes and token storage across drivers. Each provider still follows its own official OAuth rules — we do not force one HTTP shape for every API.

​
What is shared

​
Provider requirements (official docs)

Configure each driver’s oauthConfig() to match the provider — not the other way around. Sanvex maps these in OAuthProviderConfig:
  • Gmail: TokenExchangeAuth::RequestBody, TokenBodyFormat::Form, authorizationParams for Google offline consent.
  • Notion: TokenExchangeAuth::Basic, TokenBodyFormat::Json, authorizationParams: ['owner' => 'user'].
If a future provider differs (e.g. PKCE-only, custom headers), set the config fields on that driver — do not change Gmail/Notion settings to fit a generic helper.

​
Standard URLs (when routes are enabled)

Set OAuth client id and secret in .env (see the driver’s Configuration page). Built-in routes register when the client id is set, or when auth_type is oauth_2 / oauth2.

​
Adding OAuth to a new driver

  1. Read the provider’s OAuth documentation (authorize URL, required query params, token Content-Type, where client_secret goes).
  2. Implement oauthConfig() with the correct tokenExchange, tokenBodyFormat, and authorizationParams.
  3. Add config/{driver}.php, merge via mergeConfigFrom(..., 'sanvex.driver_configs.{id}'), and OAuthRoutes::registerIfConfigured('{id}') in routes/oauth.php.
  4. Document env vars on docs/drivers/{id}/configuration.md.

​
Custom flows

Use built-in routes when the default global owner and shipped scopes are enough. Use your own routes/controllers when you need different owners, scopes, or callbacks — still call $driver->oauth()->getAuthorizationUrl() / exchangeCode() with a matching OAuthProviderConfig.

​
Drivers today

See Authentication.