Email API
POST/api/email/oauth/initiate
Product availabilityAlgaPSAAlgaDesk

Initiate email OAuth flow

Starts the OAuth 2.0 authorization flow for a Google email provider. Requires a valid Auth.js session cookie. The handler builds secure OAuth state containing tenant, user, providerId, redirect URI, timestamp, and nonce, resolves the provider client ID from configured secrets, and returns the authorization URL for the browser to visit. Microsoft mailbox OAuth is not served by this unsigned route: it must be initiated from the mailbox form with an explicit application selection so the callback receives a signed state token.

Request body

Content type: application/json · schema EmailOAuthInitiateRequest

providerstringRequired
Email OAuth provider to authorize.
Enum: microsoftgoogle
redirectUristring <uri>
Optional OAuth callback URI. If omitted, the server builds /api/auth/{provider}/callback from the configured base URL.
providerIdstring <uuid>
Email provider configuration ID to carry through OAuth state and use during callback token persistence.

Response body

Success response 200 · schema EmailOAuthInitiateResponse

successbooleanRequired
OAuth initiation succeeded.
Enum: true
authUrlstring <uri>Required
Provider authorization URL for the browser to visit.
providerstringRequired
Email OAuth provider being authorized.
Enum: microsoftgoogle
statestringRequired
Base64-encoded OAuth state containing tenant, userId, providerId, redirectUri, timestamp, nonce, and hosted flag.

Response codes

200
OAuth authorization URL generated successfully.
400
Provider is missing or not supported.
401
No authenticated user session was found.
500
OAuth client ID was not configured or initiation failed unexpectedly.