Connect
Create hosted connect sessions, read their outcome and start a headless OAuth flow.
Guides: Connect flows.
| Method | Path | Operation | Scope |
|---|---|---|---|
POST | /v1/connect-sessions | Create a hosted connect session | write |
GET | /v1/connect-sessions/{sessionId} | Read a hosted connect session's outcome | read |
POST | /v1/oauth-authorizations | Start a headless OAuth connect | write |
Runs against the live API with the key you enter: this change really happens. Use a key limited to a test account.
Returns a link to the hosted connect page. Its OAuth sign-ins pass a Continue page on the API origin naming the tenant and provider, and must finish in the browser that pressed Continue (an HttpOnly cookie on the API origin); a callback in any other browser renders an error page and connects nothing. Without redirectUri the owner ends on Workwae's own confirmation page, which needs no allowlist entry; follow the outcome with GET /v1/connect-sessions/{sessionId} or the account.connected event. A failed sign-in returns with status=error and error set to a ConnectErrorCode.
Required scope: write.
application/json- body
redirectUri?stringuriproviders?array<>1 <= items[ "google", "microsoft"]microsoftCloud?MicrosoftCloud"global""global""gcc-high""dod""china"oauthAppIds?externalRef?stringlength <= 255loginHint?stringemaillength <= 320state?stringlength <= 1024accountId?stringuuidoptions?mcp?ttlSeconds?integer60 <= value <= 864003600OK
application/json- response
id*stringuuidurl*stringuriexpiresAt*stringdate-timecurl -X POST 'https://api.workwae.com/v1/connect-sessions' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "c4e6a8b0-1d3f-4a5c-8e7b-9d1f3a5c7e9b", "url": "https://app.example.com/", "expiresAt": "2026-05-04T09:30:00.000Z"}Runs in your browser against api.workwae.com with the key you enter. Use a read-only key, limited to a test account if you can.
Required scope: read.
sessionId*stringuuidOK
application/json- response
id*stringuuidstatus*ConnectSessionStatus"pending""completed""failed"error*|nullaccountId*|nullemail*string|nullmcpKeyId*|nullmcpKeySkipped*|nullexpiresAt*stringdate-timecreatedAt*stringdate-timecurl -X GET 'https://api.workwae.com/v1/connect-sessions/6479c36f-cac9-42db-8efa-f6e3f731ba08'{ "id": "c4e6a8b0-1d3f-4a5c-8e7b-9d1f3a5c7e9b", "status": "pending", "error": "session_used", "accountId": "6f1c2a4e-8b3d-4e5f-9a7b-1c2d3e4f5a6b", "email": "string", "mcpKeyId": "0f631a79-440a-4430-8c42-145950e24fef", "mcpKeySkipped": "mcp_key_limit", "expiresAt": "2026-05-04T09:30:00.000Z", "createdAt": "2026-05-04T09:30:00.000Z"}Runs against the live API with the key you enter: this change really happens. Use a key limited to a test account.
authorizeUrl is a page on the API origin naming the tenant and the provider; only its Continue button (a form POST, accepted only from the API or console origin) leads on to the provider. Continuing works once and binds the sign-in to that browser with an HttpOnly cookie scoped to the callback; a callback arriving in any other browser renders an error page and connects nothing, so send the user's own browser to it. A failed sign-in returns with status=error and error set to a ConnectErrorCode.
Required scope: write.
application/json- body
provider*OAuthProvider"google""microsoft"redirectUri*stringurimicrosoftCloud?MicrosoftCloud"global""global""gcc-high""dod""china"oauthAppId?stringuuidexternalRef?stringlength <= 255state?stringlength <= 1024accountId?stringuuidoptions?OK
application/json- response
authorizeUrl*stringuricurl -X POST 'https://api.workwae.com/v1/oauth-authorizations' \ -H 'Content-Type: application/json' \ -d '{ "provider": "google", "redirectUri": "https://app.example.com/mail/connected"}'{ "authorizeUrl": "https://app.example.com/"}