Skip to main content
POST
Start a Calendly connection
Requires Admin or Owner. Send no request body. API-key requests require the workspace header; bearer requests use the account’s selected workspace.
  1. Before starting, sign in to Agent Builder in the browser you will use for consent. Use the same account as the request credential’s owner and select the workspace you intend to connect. Keep that session and workspace selection throughout authorization.
  2. Call this endpoint and read authorization_url.
  3. Open that URL in the signed-in browser to approve Calendly scheduling read/write access. An API key does not replace Calendly consent.
  4. Calendly redirects to Agent Builder’s /integrations/calendly/callback page. The page uses the existing session to submit Complete authorization automatically.
  5. Read connection status. Select the linked Calendly tools in each agent that should use them; connecting does not select tools automatically.
The pending authorization expires after 10 minutes and is bound to the initiating user and workspace. Starting another attempt replaces the previous pending attempt. Do not log or reuse the returned authorization URL. If the browser session is missing or the wrong account/workspace is selected, the callback cannot resume after you sign in: correct the session and start a fresh connection attempt. This operation can contact Calendly for authorization discovery and client registration. Provider failures can return 502; an unavailable callback configuration returns 503. Start a fresh attempt if the authorization expires.

Authorizations

Authorization
string
header
required

Bandwidth Labs OAuth access token. Uses the user's selected workspace; the workspace header is not required. Do not also send an API key. Bearer-only operations may additionally require the Labs super_user role.

Headers

X-VOAI-ORGANIZATION-ID
string | null

Required with X-BW-LABS-AGENTS-API-KEY: the positive local workspace ID to access. The key owner must be a current member. Missing or invalid IDs return 400; non-member workspaces return 403. Not required for bearer authentication, which uses the user's selected workspace.

Response

Successful Response

authorization_url
string
required

Short-lived URL for interactive Calendly consent. The pending attempt expires after 10 minutes.