Connect flows

Every mailbox Workwae reads is an account. This page covers the ways a user connects one, the OAuth apps behind the sign-in, and how to reconnect an account whose grant stopped working.

Choose a flowCopy Anchor Link

The browser flows end the same way: the user returns to your redirectUri, which must be on the 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 allowlistCopy Anchor Link

The tenant setting redirectUris lists where connect flows may send the user back. Edit it on the console's Settings page or with PATCH /v1/settings (admin scope).

• Up to 50 entries, each an absolute https URL. 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 redirect_uri_not_allowed.
• A session whose address is removed from the list afterwards stops working.

Hosted connect sessionsCopy Anchor Link

Create a session and send the user's browser to its url before expiresAt.

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 }
}'

options sets up the account:

• calendarEnabled, contactsEnabled: also sync calendars and contacts. Their scopes are asked for only when your plan includes the module.
• bodyStorage: whether message content is stored (see Read mail).
• mailAccess: api (default) or imap, which reads the mailbox over IMAP with the OAuth grant. See IMAP with OAuth.
• sharedMailboxesEnabled: Microsoft only; lets the account open the shared mailboxes its user can access.

With mcp, the session needs the admin scope. Once completed it names the minted key as mcpKeyId; when the account already holds 25 keys, it mints none and answers mcpKeySkipped.

Errors creating a sessionCopy Anchor Link

Handle the returnCopy Anchor Link

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>

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

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

curl "https://api.workwae.com/v1/connect-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $WORKWAE_API_KEY"

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

Headless OAuthCopy Anchor Link

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

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"
}'

It takes provider (google or microsoft) and the same redirectUri, state, externalRef, accountId, microsoftCloud and options as a session, with one oauthAppId instead of oauthAppIds.

Import a refresh tokenCopy Anchor Link

When your own OAuth app already holds 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 Workwae's app. The account's address is the one the provider reports for the grant.

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"
}'

The token is checked with the provider before the account is created. Refusals answer 400 with invalid_grant (revoked, expired or never valid), invalid_client, scope_denied, token_exchange_failed or identity_failed; the full list is in the Accounts reference.

Your own OAuth appsCopy Anchor Link

By default users sign in through Workwae's Google and Microsoft apps. Register your own to show your name on the consent screen and own the grant.

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"
}'

• PATCH /v1/oauth-apps/{appId} changes the name, client secret or authority. Accounts on the app use a new secret from their next token refresh.
• An app cannot be deleted while accounts still use it.

Gmail pushCopy Anchor Link

Accounts on your own Google app can receive Gmail changes by push instead of polling.

1. In the app's Cloud project, create a Pub/Sub topic and an authenticated push subscription to the app's gmailPushEndpoint, which is also the token audience. Settings > OAuth apps in the console shows a ready gcloud script.
2. Set gmailPush (topic, serviceAccount) with PATCH /v1/oauth-apps/{appId}.

Setting it wakes the app's accounts so it applies at once; saving it again retries a watch Gmail refused. gmailPush: null stops the watches and returns the accounts to polling.

Microsoft cloudsCopy Anchor Link

microsoftCloud applies to sign-ins with Workwae's app, for the clouds Workwae runs one in; for a cloud without one, headless OAuth and import answer 400 provider_not_configured. For other clouds, register your own app per cloud; the app carries its cloud. The account reports it as cloud.

Reconnect an accountCopy Anchor Link

When a provider revokes a grant (a password change, an administrator 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.
• Headless OAuth 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.
• Accounts from an organization connection or a shared mailbox are restored through the connection or the delegating account instead.