SapanCalDeveloper Docs

Create a connect session

Starts connecting (or relinking) a calendar account for one of your users. Send the user to the returned url: the hosted page lets them pick Google or Microsoft and sign in.

When the flow ends the user is redirected (303) to redirect_uri with connect_session_id, status (success, denied or error) and, on error, error_code in the query string. Confirm the outcome with GET /connect_sessions/{connect_session_id} (or the connection.created webhook) rather than trusting the query string.

Sessions expire after 30 minutes. Pass connection_id to relink a connection whose status is relink_required.

POSThttps://api.bentocal.com/au/v1/connect_sessions

Authentication

AuthorizationstringheaderBearer <token>required

An API key: bc_{live|test}_{region}_…, from the console.

Request body

application/jsonrequired
  • user_idstringlength: 1…255required

    Your own identifier for the end user (1–255 characters). The prefix bentocal-test: is reserved.

  • redirect_uristringurirequired

    Where the user is sent when the flow ends. Must exactly match one of the application's registered redirect URIs.

  • providerstringgoogle | microsoft

    Offer only this provider on the connect page. The page still shows, so the user can accept the terms.

  • connection_idstring

    Relink this existing connection (it must belong to user_id). The user must sign in to the same provider account.

Responses

A one-time link that takes an end user through connecting a calendar account.

  • idstringrequired

    Connect session id (cs_…).

  • statusstringrequired

    pending: created, not opened. redirected: the user went to the provider. completed: a connection was made or relinked. denied: the user declined at the provider. error: see error_code. expired: not finished in time.

  • user_idstringrequired
  • urlstringurirequired

    The hosted connect page. Send the user here.

  • expires_atstringdate-timerequired

    When the session expires (30 minutes after creation).

  • connectionany ofrequired

    The connection made or relinked, once status is completed.

  • error_codestring | nullrequired

    Why the session ended in error: account_mismatch (a relink signed in to a different account), connection_limit_reached, connection_not_found (the connection being relinked was deleted), session_expired or internal_error. New codes may be added.

Errors