Begin connecting a Google mailbox

Mint a single-use, workspace-bound authorisation attempt and return its URL.

Not idempotent, and deliberately so: each call is one attempt, expiring on its own, and abandoning one costs nothing. login_hint pre-selects an account on Google's screen. It is a convenience only, since the address that is actually connected is read back from Google and never from this parameter.

Tenancy: the request is scoped to one workspace, and the credential presented is what selects it. A caller with no membership in that workspace is refused with 404, which is indistinguishable from a workspace that does not exist.

Authorisation: admin or owner. An editor or viewer receives 403 insufficient_role.

Access: Authorization: Bearer carrying either a realm access token or an API key. A key must hold the channels:write scope, and the workspace role of the person who owns it must meet the floor above.

Query Parameters

Response Body

curl -X GET "https://example.com/v1/channels/email/oauth/google/start"

{  "authorization_url": "string",  "expires_at": "string"}