Connect an end user's account

Give Ana access to her own Google Calendar, verify the result and let her revoke it.

Run this flow on your backend with your organization's token. Ana is a person in your product, identified by your stable id user:ana. She does not need a telipot account.

Prepare the callback

Choose a callback in your application, such as https://your-app.example/connected. Add it under Settings → Redirect allowlist on the dashboard. telipot matches the scheme, host, port and path; allowlist entries contain no query or fragment.

You can also manage it through the API:

Shell

curl https://api.telipot.com/v1/connect/redirect-uris \
  -H "Authorization: Bearer $TELIPOT_TOKEN"

Shell

curl -X PUT https://api.telipot.com/v1/connect/redirect-uris \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"redirect_uris":["https://your-app.example/connected"]}'

PUT replaces the entire list. Preserve existing entries when adding a callback. HTTPS is required; local development also accepts HTTP on localhost or 127.0.0.1.

Google Calendar supports a managed OAuth app or your organization's own app. If the gateway has no configured managed app, set up your own under Providers → Google Calendar → OAuth app. An oauth_app_required refusal explains this prerequisite.

Create the connect session

Request the catalog scope calendar.readonly to read Ana's calendars and events:

Shell

curl https://api.telipot.com/v1/connect/sessions \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"google-calendar","principal":"user:ana","scopes":["calendar.readonly"],"redirect_uri":"https://your-app.example/connected"}'

The response contains session_id, url and expires_at. Store the session id against Ana in your backend, then send her to url. Treat the full hosted URL as secret: it works once and expires after fifteen minutes.

For an organization account, use principal: "organization" and a provider that supports it, such as Search Console. Google Calendar's tasks require an end user; changing the principal does not turn them into organization tasks.

Verify the callback

After consent, telipot redirects to your callback with session_id and status=completed. Verify the session with your backend token rather than trusting those query parameters alone:

Shell

curl https://api.telipot.com/v1/connect/sessions/REPLACE_WITH_SESSION_ID \
  -H "Authorization: Bearer $TELIPOT_TOKEN"

Check that the response belongs to the session you stored for Ana, names user:ana and google-calendar, and has status: "completed" and a connection_id. The other session statuses are pending and expired.

Denied or failed consent stays on a hosted recovery page. Do not infer success because the browser opened a link. If a link expires, create a fresh session for the same principal and callback.

Run as Ana

Shell

curl https://api.telipot.com/v1/tasks/google-calendar.events.list/run \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Telipot-Principal: user:ana" \
  -H "Content-Type: application/json" \
  -d '{}'

The provider output is unchanged. The receipt identifies Ana, her connection and a $0 charge from telipot. Her first connection is the default. With multiple Calendar accounts, select a default or send Telipot-Connection with the chosen connection id; telipot does not guess.

Recover from a refusal

Code	Next step
`principal_required`	Name the end user with `Telipot-Principal` or the request's receipt options
`grant_required`	Open `connect_url` when present, or create a session for the same person
`scope_required`	Use the supplied connect link to add the missing scopes on the same account
`connection_invalid`	Use the supplied reconnect link to sign in again on the same account
`connection_ambiguous`	Choose one of `candidates`; send its id as `Telipot-Connection` or set a default
`oauth_app_required`	Configure the organization's OAuth app on that provider

Use recovery links returned by telipot rather than silently changing the principal or borrowing another account. Never fall through to a paid credential after a customer credential fails.

Let Ana revoke access

Your backend can create a signed page showing only Ana's connections:

Shell

curl https://api.telipot.com/v1/connect/connections-pages \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"principal":"user:ana"}'

Hand its url to Ana. It lets her review and revoke her connections without a telipot login. Respect the response's expires_at and create another page when needed.

An owner/admin can also revoke a connection from the dashboard. A backend organization token can use DELETE /v1/connections/{id}. Revocation stops future calls using that connection; it does not erase past audit records. The next account task requires fresh consent.

Continue with SDK connect or CLI connect to use the same flow from code.