Start connecting an outside account

integrations.connect

GET/api/v1/households/{household_id}/integrations/{service}/connect

Route

Browser navigation only. Redirects to the provider's consent screen for the service's scopes. After the provider returns to the callback, the browser lands on return_to with integration_connected (the new integration's ID) or integration_error. Only OAuth services connect this way; a mailbox over IMAP is connected by the email app.

Parameters#

Start connecting an outside account: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`service`pathone of: google_calendar, gmail, google_drive, imaprequired	The service to connect: google_calendar, gmail or google_drive.
`return_to`querystringoptional	App path to open afterwards, such as /calendar/settings. Other origins and API paths are ignored.

Response#

302 Redirect to the provider, or back to the app with integration_error=not_configured. No body.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Start connecting an outside account: errors
Status	Code	When
`401`	`unauthenticated`	The request has no valid session.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Start connecting Google Calendar

A browser navigation. The API sets short-lived cookies for the flow and redirects to Google's consent screen for the scopes the service needs.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/integrations/google_calendar/connect?return_to=/calendar/settings' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/integrations/google_calendar/connect?return_to=/calendar/settings", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/integrations/google_calendar/connect?return_to=/calendar/settings HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 302

HTTP/1.1 302 Found
X-Request-Id: req_01M6V9CSTCYAGMXCXZ29SZ15HC
Location: https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id=example.apps.googleusercontent.com&redirect_uri=https%3A%2F%2Frigel.house%2Fapi%2Fv1%2Fintegrations%2Fgoogle%2Fcallback&state=bkFAFL19JVpMKKoJbXhTR_bV5aEuYeVXc30ixzrrCVc&code_challenge_method=S256&code_challenge=WDbFCXZ96GXUydCM5i19LwunqeS6zqnxlhbl01A9gv4&scope=openid+email+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendarlist.readonly&access_type=offline&prompt=consent

A service that isn't connected this way

A mailbox over IMAP is connected by the email app, not through Google.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/integrations/imap/connect' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/integrations/imap/connect", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/integrations/imap/connect HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01M6V9CSTJ1FYG6WGCTHXDPQ83

{
  "error": {
    "code": "not_found",
    "message": "That service wasn't found.",
    "details": {},
    "recovery": "Check the ID. You can only reach households you're a member of.",
    "request_id": "req_01M6V9CSTJ1FYG6WGCTHXDPQ83"
  }
}