Finish connecting a Google account
integrations.google.callback
GET/api/v1/integrations/google/callback
- Route
- Public
Google redirects here; don't call it directly. Always redirects to the return_to from when connecting started (or /), never with a JSON error. On success the redirect carries integration_connected with the integration's ID. On failure it carries integration_error: not_configured (no Google client or no credential keys), cancelled (the person backed out at Google), provider_failed (the request expired or Google refused it; start again), scopes_missing (the person unticked a permission the service needs; nothing was stored), household_not_found (they're not a member any more) or signed_out (the session ended during the flow).
Parameters#
| Field | Description |
|---|---|
codequerystringoptional | Authorization code from Google. |
statequerystringoptional | Must match the state set when connecting started. |
errorquerystringoptional | Error from Google, such as access_denied when the person cancels. |
Response#
302 Redirect to the app, connected or with integration_error. No body.
Errors#
Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.
| Status | Code | When |
|---|
Examples#
These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.
Finish connecting Google Calendar
Google sends the browser back with a code. The API stores the account's credential, encrypted, and redirects with the new integration's ID.
curl 'https://rigel.house/api/v1/integrations/google/callback?code=4/0AfJohXnZq8wHt3uYeRvKo&state=bkFAFL19JVpMKKoJbXhTR_bV5aEuYeVXc30ixzrrCVc'const response = await fetch("https://rigel.house/api/v1/integrations/google/callback?code=4/0AfJohXnZq8wHt3uYeRvKo&state=bkFAFL19JVpMKKoJbXhTR_bV5aEuYeVXc30ixzrrCVc");
const data = await response.json();GET /api/v1/integrations/google/callback?code=4/0AfJohXnZq8wHt3uYeRvKo&state=bkFAFL19JVpMKKoJbXhTR_bV5aEuYeVXc30ixzrrCVc HTTP/1.1
Host: rigel.houseHTTP/1.1 302 Found
X-Request-Id: req_01M6V9CSTEPBS1HDC29KM081M4
Location: https://rigel.house/calendar/settings?integration_connected=int_01M6V9CSTFHJQXMXWK5DX51W4VCancel at Google
The person backs out at the consent screen. The redirect says integration_error=cancelled, and nothing is stored.
curl 'https://rigel.house/api/v1/integrations/google/callback?error=access_denied&state=bkFAFL19JVpMKKoJbXhTR_bV5aEuYeVXc30ixzrrCVc'const response = await fetch("https://rigel.house/api/v1/integrations/google/callback?error=access_denied&state=bkFAFL19JVpMKKoJbXhTR_bV5aEuYeVXc30ixzrrCVc");
const data = await response.json();GET /api/v1/integrations/google/callback?error=access_denied&state=bkFAFL19JVpMKKoJbXhTR_bV5aEuYeVXc30ixzrrCVc HTTP/1.1
Host: rigel.houseHTTP/1.1 302 Found
X-Request-Id: req_01M6V9CSTJ51AMKX6B952XS2MZ
Location: https://rigel.house/calendar/settings?integration_error=cancelled