Organization connections

An organization connection lets a Google Workspace or Microsoft 365 administrator authorize Workwae once. You then list the directory and add mailboxes by address. Each becomes an account that syncs, sends and announces account events like one a user connected, without any user signing in.

Choose an access methodCopy Anchor Link

For a single Microsoft 365 shared mailbox, a user's own grant is enough. Gmail has no delegated shared mailboxes: use domain-wide delegation there.

A connection's status tracks whether it works:

A missing optional permission limits only calendar, contacts or the directory; mail keeps syncing. For Google, the administrator must authorize every scope the connection lists, or no token is issued.

Google Workspace delegationCopy Anchor Link

jq -n --rawfile key service-account.json '{
  kind: "google_delegation",
  name: "Acme Workspace",
  domain: "acme.com",
  serviceAccountKey: $key,
  calendarEnabled: true,
  contactsEnabled: true,
  directoryAdmin: "it-admin@acme.com"
}' | curl -X POST "https://api.workwae.com/v1/org-connections" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d @-

curl -X POST "https://api.workwae.com/v1/org-connections/$CONNECTION_ID/test" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "user": "ada@acme.com" }'

Then add mailboxes.

Microsoft 365 app-only accessCopy Anchor Link

A Microsoft connection names its cloud: global (worldwide, including GCC; the default), gcc-high, dod or china (21Vianet). Sign-in and Graph calls stay in that cloud.

curl -X POST "https://api.workwae.com/v1/org-connections" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
  "kind": "microsoft_app",
  "name": "Contoso (GCC High)",
  "cloud": "gcc-high",
  "credential": { "type": "client_secret", "clientId": "'"$CLIENT_ID"'", "clientSecret": "'"$CLIENT_SECRET"'" }
}'

curl -X POST "https://api.workwae.com/v1/org-connections/$CONNECTION_ID/consent" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "redirectUri": "https://app.example.com/admin/consent-done", "state": "tenant-7" }'

Add mailboxesCopy Anchor Link

Both kinds list their directory and add mailboxes the same way.

• GET /v1/org-connections/{connectionId}/directory-entries pages through the directory: up to 200 entries a page (default 100), query matching the start of names and addresses. Each entry's accountId names the account already added for it. A nextCursor is good for an hour, on this connection only.
• Listing needs User.Read.All (Microsoft) or a directory admin (Google).
• POST /v1/org-connections/{connectionId}/accounts adds up to 100 mailboxes per call, with optional settings for the new accounts.

curl -X POST "https://api.workwae.com/v1/org-connections/$CONNECTION_ID/accounts" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "mailboxes": [{ "email": "support@acme.com" }, { "email": "sales@acme.com" }] }'

Each mailbox is checked through the connection first (Google: a delegated token for it; Microsoft: its inbox). Every address gets its own result, in request order: created, exists (a live account was already there) or failed with the reason the API would answer:

Shared mailboxesCopy Anchor Link

Open a Microsoft 365 shared mailbox as an account of its own, through the grant of an account whose user can open it. Shared mailboxes need the shared mailboxes module in your plan (403 plan_module_unavailable).

curl -X POST "https://api.workwae.com/v1/accounts/$USER_ACCOUNT_ID/shared-mailboxes" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "email": "billing@contoso.com" }'

If the delegating account is deleted, the shared mailbox moves to reauth_required with delegate_missing.

When access changesCopy Anchor Link

• When an administrator withdraws authorization, the affected accounts move to reauth_required with consent_revoked, and account.reauth_required is sent.
• Once access is restored, a passing test returns them to active and sends account.connected with reauthorized: true.
• Accounts added through a connection belong to it: a user sign-in cannot take them over. Fix the connection, then test it.
• Replacing a credential or the authorized scopes (PATCH /v1/org-connections/{connectionId}) makes the connection unverified until the next test.
• A connection cannot be deleted while live accounts use it (409 connection_in_use). Delete its accounts first.

Every route is in the Organization connections and Shared mailboxes references.