OAuth Token Management

OAuth tokens are managed by the OAuthTokenManager service. Tokens are encrypted at rest using Laravel's Crypt facade and stored in the credentials column of the integration_connections table.

Token Lifecycle

1. Connection Created -- Admin creates an IntegrationConnection on the Integrations page
2. Authorization -- Admin clicks "Connect" and is redirected to the OAuth provider
3. Callback -- Provider redirects back with an authorization code
4. Exchange -- Code is exchanged for access + refresh tokens via GenericOAuthIntegration::exchangeOAuthCode()
5. Storage -- Tokens are encrypted and stored in the connection's credentials column
6. Post-Callback -- afterOAuthCallback() hook runs (e.g., scope validation, fetching account email)
7. Refresh -- Before expiration, the access token is automatically refreshed via refreshOAuthToken()
8. Reuse -- The connection can be selected in multiple form integrations

OAuth Routes

GET  /filaforms/connections/oauth/redirect/{connection}  -> Start OAuth flow
GET  /filaforms/connections/oauth/callback                -> Handle callback

The callback URL is fixed (no dynamic segments). The connection ID is passed via the OAuth state parameter. This is required because providers like Google don't support wildcards in redirect URIs.

Token Storage

Tokens are stored in the IntegrationConnection model's encrypted credentials column:

use FilaForms\Integrations\Data\OAuthTokenData;

$tokenData = OAuthTokenData::from([
    'accessToken' => 'ya29.a0...',
    'refreshToken' => '1//0e...',
    'expiresAt' => now()->addHour(),
    'scopes' => ['https://www.googleapis.com/auth/spreadsheets'],
]);

The OAuthTokenManager handles reading, writing, and refreshing tokens:

// Get a valid token (auto-refreshes if expired)
$token = $tokenManager->getValidToken($connection);

// Store new tokens after OAuth exchange
$tokenManager->store($connection, $tokenResponse);

// Delete tokens (disconnect)
$tokenManager->delete($connection);

Local Development

For local development with Laravel Herd (.test domains), use fwd.host as a proxy:

FILAFORMS_OAUTH_CALLBACK_URL=https://fwd.host/http://your-site.test/filaforms/connections/oauth/callback

The OAuth controller checks this config value and uses it when present. In production, omit the variable to use the default route URL.