Connect flows

Three ways to connect

The two browser flows end the same way: the user returns to your redirectUri, which must be on the tenant allowlist. A hosted session may leave it out; the user then ends on a workwae confirmation page and you read the outcome from the session.

Redirect URI allowlist

• settings.redirectUris lists up to 50 addresses. Edit it on the board's Settings page or with PATCH /v1/settings (admin scope).
• Entries must be absolute https URLs; plain http is accepted only for localhost and 127.0.0.1.
• A redirect URI is allowed when its origin and path exactly match an entry. The query string and fragment are yours to vary.
• Anything else answers 400 with reason redirect_uri_not_allowed. A session whose address was removed from the list afterwards stops working.

Hosted connect sessions

curl -X POST "https://api.workwae.com/v1/connect-sessions" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "redirectUri": "https://app.example.com/mail/connected",
  "providers": ["google", "microsoft"],
  "externalRef": "user_42",
  "state": "csrf-token",
  "options": { "calendarEnabled": true }
}'

The return trip

The browser comes back to your redirect URI with the outcome in the query string:

?status=success&account_id=<id>&state=<your state>
?status=error&error=<code>&state=<your state>

Without a redirectUri, follow the session instead: GET /v1/connect-sessions/{sessionId} answers its status (pending, completed or failed), the error code of a failure, and the accountId and email it connected.

Treat a code not listed here as a failed attempt: new codes may be added. If the return address is no longer in your allowed redirect URIs, the user sees an error page instead, since there is nowhere safe to send them.

Check state against what you sent, then use the account id. The account.connected event announces the same account to your webhooks.

Headless OAuth

With your own provider picker, ask for the authorization URL directly and redirect the user to it. The callback, the account creation and the return to your redirect URI work exactly as for hosted sessions.

The URL is a page on the API origin that names your organization and the provider; the user continues to the provider with its button. Continuing works once and binds the sign-in to that browser with an HttpOnly cookie. Redirect the user's own browser to it; a callback arriving in any other browser gets an error page and connects nothing.

curl -X POST "https://api.workwae.com/v1/oauth-authorizations" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "provider": "microsoft",
  "redirectUri": "https://app.example.com/mail/connected",
  "state": "csrf-token"
}'
# => { "authorizeUrl": "https://api.workwae.com/connect/authorize?key=..." }

Import a refresh token

When your own OAuth app already obtained a refresh token with the mail (and calendar) scopes, connect the account without a browser. Name the app with oauthAppId (registered below); omit it for tokens issued to the platform app.

curl -X POST "https://api.workwae.com/v1/accounts" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "provider": "google",
  "refreshToken": "1//0g...",
  "oauthAppId": "6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b",
  "externalRef": "user_42"
}'

Your own OAuth apps

By default users sign in through the platform's Google and Microsoft apps. Register your own to show your name on the consent screen and own the grant. Register these redirect URIs with the provider:

https://api.workwae.com/connect/callback/google
https://api.workwae.com/connect/callback/microsoft

curl -X POST "https://api.workwae.com/v1/oauth-apps" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "provider": "microsoft",
  "cloud": "global",
  "name": "Example Mail",
  "clientId": "00000000-0000-0000-0000-000000000000",
  "clientSecret": "...",
  "authority": "common"
}'

• Microsoft apps need a cloud: each cloud needs its own app registration. authority is the directory (tenant) id, or common.
• Use an app by passing its id as oauthAppIds (hosted sessions) or oauthAppId (headless and import).
• Google apps can push Gmail changes instead of polling: create a topic and an authenticated push subscription in the app's Cloud project and set gmailPush (topic, serviceAccount) with PATCH /v1/oauth-apps/{appId}. The subscription delivers to the app's gmailPushEndpoint, which is also the token audience. Settings > OAuth apps shows a ready gcloud script.
• An app cannot be deleted while accounts still use it.

Microsoft clouds

microsoftCloud applies to sign-ins with the platform app; a tenant app carries its own cloud. The account reports it as cloud.

Reauthorization

When a provider revokes a grant (a password change, an admin removing consent), the account moves to reauth_required and an account.reauth_required event names the reason. Send the user through a connect flow again with the account's id:

curl -X POST "https://api.workwae.com/v1/connect-sessions" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "redirectUri": "https://app.example.com/mail/connected",
  "accountId": "6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b"
}'

• The session signs in to the account's own provider, cloud, OAuth app and mail access; providers must include that provider. A password IMAP account gets the IMAP form.
• The headless flow takes accountId too, with the account's address as the sign-in hint.
• On success the same account becomes active again and account.connected is sent with reauthorized: true.