Skip to main content
POST
Complete Calendly authorization
Requires Admin or Owner and the same Agent Builder user and workspace that started the connection. This is an authenticated application endpoint, not a public provider webhook. The Agent Builder callback page normally calls it after the browser returns from Calendly. Send the returned state and authorization code. If Calendly denied authorization, send its error instead. Values in generated examples are placeholders; only a result from the pending authorization attempt can succeed. Do not log authorization codes or state. State is single-use and is consumed before token exchange. Invalid, expired, cancelled, or wrong-user/workspace attempts return 400. Replaced attempts or authorization requiring reconnection can return 409; provider failures can return 502. After a failed exchange, start a new connection rather than replaying the callback. Success returns the connection status. Inspect state: HTTP 200 can contain discovery-failed or reconnect-required. A connected result includes the discovered tool catalog; agents must still select the linked tools. Connecting a different Calendly account disables the old tool link instead of giving existing agent selections access to the new account.

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.

Body

application/json
state
string
required

Single-use state returned by the pending authorization attempt for this user and workspace.

Required string length: 1 - 256
code
string | null

Authorization code returned by Calendly after consent; omit when sending an authorization error.

Maximum string length: 4096
error
string | null

Provider authorization error, such as access_denied, when consent did not complete.

Maximum string length: 256

Response

Successful Response

can_manage
boolean
required

Whether the caller is an Admin or Owner who can change this workspace connection.

state
enum<string>
required

Connection readiness. Inspect this field even after HTTP 200; cached tools may remain while the connection is unusable.

Available options:
not-connected,
connected,
reconnect-required,
discovery-failed
account_name
string | null

Connected account display name; may remain after disconnect.

integration_id
string | null

Workspace integration identifier, or null before a connection record exists.

last_synced_at
number | null

Unix timestamp in seconds of the last successful discovery, or null.

tool_uuid
string | null

Linked managed tool group UUID. Select its tools for agents explicitly.

tools
CalendlyTool · object[]

Cached provider tool catalog. Use only while state is connected; discovery is not permission to execute every tool.