Your own OAuth apps

By default users sign in through Workwae's Google and Microsoft apps. Register your own app to:

• Show your name and logo on the provider's consent screen. The grant belongs to your client.
• Connect Gmail over IMAP and SMTP. Workwae's Google app connects Gmail only through the Gmail API.
• Receive Gmail changes by push instead of polling.
• Use Gmail API quota from your own Cloud project.
• Sign in to a Microsoft cloud where Workwae runs no app.

Each provider sends the sign-in back to Workwae at its redirect URI, the same in every cloud. It is not your app's return address, which goes on the redirect URI allowlist.

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

To put the redirect URI on a domain you own, set up a connect domain.

Create a Google OAuth clientCopy Anchor Link

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

ScopesCopy Anchor Link

Workwae asks for these scopes at sign-in, according to the account's options. Calendar and contacts scopes are asked for only when the workspace's plan includes that module.

• Google lets users untick scopes on the consent screen. A sign-in that is missing a scope the account needs fails with scope_denied.
• Workwae reads the mailbox address from Google's userinfo endpoint and accepts only a verified address.

Audience and verificationCopy Anchor Link

A Google account holds at most 100 refresh tokens for one client. Issuing another one silently invalidates the oldest token. Reconnect an existing account with its accountId instead of connecting the mailbox again.

Create a Microsoft Entra appCopy Anchor Link

Each cloud needs its own app registration, created in that cloud's portal:

Supported account types and authorityCopy Anchor Link

Personal Microsoft accounts (Outlook.com) exist only in the global cloud.

Register the app with WorkwaeCopy Anchor Link

In the console, open Settings > Provider apps and choose Register app under OAuth apps. Admins and owners can register apps. With the API, POST /v1/oauth-apps needs the admin scope.

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

The response's redirectUri is the redirect URI to register at the provider.

• A Google app given cloud or authority answers 400 not_microsoft.
• provider, cloud and clientId cannot be changed. Register a new app instead.
• Workwae does not check the credentials when you register them. Connect a mailbox to test the app.

Use the appCopy Anchor Link

Pass the app's id as oauthAppIds on a hosted session, or as oauthAppId for headless OAuth and refresh-token import. A Microsoft app signs in to its own cloud, whatever microsoftCloud says.

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",
  "oauthAppIds": { "google": "'"$GOOGLE_APP_ID"'", "microsoft": "'"$MICROSOFT_APP_ID"'" }
}'

Connect one mailbox through each new app to test it. Setup errors appear like this:

The full list is in Handle the return.

Rotate the client secretCopy Anchor Link

1. Add a new secret to the app at the provider. Keep the old one.
2. Replace the secret in Workwae: Replace client secret in the console, or PATCH /v1/oauth-apps/{appId} with clientSecret. Accounts use the new secret from their next token refresh.
3. Delete the old secret at the provider.

PATCH also changes name, authority, useConnectDomain and gmailPush. An app cannot be deleted while accounts still use it (409 oauth_app_in_use).

Your own redirect domainCopy Anchor Link

A connect domain puts the redirect URI on a hostname you own, such as connect.example.com, instead of api.workwae.com. Google's verification needs this. The domain serves only the browser steps of a sign-in through your own apps: the page before the provider, the redirect URI and the MCP key page. Workwae's own apps always use api.workwae.com.

curl -X PUT "https://api.workwae.com/v1/settings/connect-domain" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "hostname": "connect.example.com" }'

https://connect.example.com/connect/callback/google
https://connect.example.com/connect/callback/microsoft

curl -X PATCH "https://api.workwae.com/v1/oauth-apps/$APP_ID" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "useConnectDomain": true }'

• Accounts already connected keep working: a token refresh sends no redirect URI.
• If the domain stops being active, sign-ins through apps that use it fail with connect_domain_inactive. Workwae does not fall back to api.workwae.com, whose redirect URI the provider may no longer accept.
• The domain cannot be removed or replaced while anything uses it (409 connect_domain_in_use). Turn useConnectDomain off first, after adding the api.workwae.com redirect URI back at the provider.
• Meeting apps that sign users in and Microsoft organization connections with your own app registration take the same useConnectDomain.

Gmail pushCopy Anchor Link

Accounts on your own Google app can receive Gmail changes by push instead of polling. Gmail accepts a watch topic only in the Cloud project of the app's OAuth client, so you create the topic and its push subscription in that project.

PROJECT=my-project  # the project of the app's OAuth client
TOPIC=workwae-gmail
SA=workwae-gmail-push@$PROJECT.iam.gserviceaccount.com
ENDPOINT=...        # the app's gmailPushEndpoint
gcloud services enable pubsub.googleapis.com --project "$PROJECT"
gcloud pubsub topics create "$TOPIC" --project "$PROJECT"
# Gmail publishes as this account; grant publish to nobody else.
gcloud pubsub topics add-iam-policy-binding "$TOPIC" --project "$PROJECT" \
  --member serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role roles/pubsub.publisher
gcloud iam service-accounts create workwae-gmail-push --project "$PROJECT" \
  --display-name "Workwae Gmail push"
# Only the Pub/Sub service agent of the subscription's project may mint push tokens for it.
PROJECT_NUMBER=$(gcloud projects describe "$PROJECT" --format 'value(projectNumber)')
gcloud iam service-accounts add-iam-policy-binding "$SA" --project "$PROJECT" \
  --member "serviceAccount:service-$PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com" \
  --role roles/iam.serviceAccountTokenCreator
gcloud pubsub subscriptions create workwae-gmail-push --project "$PROJECT" \
  --topic "$TOPIC" \
  --push-endpoint "$ENDPOINT" \
  --push-auth-service-account "$SA" \
  --push-auth-token-audience "$ENDPOINT" \
  --ack-deadline 30 \
  --message-retention-duration 600s \
  --min-retry-delay 10s --max-retry-delay 120s \
  --expiration-period never

curl -X PATCH "https://api.workwae.com/v1/oauth-apps/$APP_ID" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "gmailPush": {
    "topic": "projects/my-project/topics/workwae-gmail",
    "serviceAccount": "workwae-gmail-push@my-project.iam.gserviceaccount.com"
  }
}'

• Saving gmailPush wakes the app's accounts so it applies at once. Saving it again retries a watch that Gmail refused.
• A refused watch leaves the account polled. Its runtime detail shows gmail_watch_refused when the topic is in another project or Gmail may not publish to it.
• Workwae accepts a push only with a token for this app's endpoint, signed for its service account.
• gmailPush: null stops the watches and returns the accounts to polling.