> ## Documentation Index > Fetch the complete documentation index at: https://docs.agents.labs.bandwidth.com/llms.txt > Use this file to discover all available pages before exploring further. # Complete Calendly authorization > Exchange a pending authorization result and discover workspace Calendly tools. Requires Admin or Owner and the same Agent Builder user and workspace that started [the connection](https://docs.agents.labs.bandwidth.com/api-reference/calendly/connect.md). 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](https://docs.agents.labs.bandwidth.com/api-reference/calendly/status.md). 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. ## OpenAPI ````yaml POST /api/v1/integrations/calendly/callback openapi: 3.1.0 info: title: Bandwidth Agent Builder API version: v1 description: >- Manage agents, place calls, and retrieve conversation results in your workspace. servers: - url: https://agents.labs.bandwidth.com description: Workspace API security: [] paths: /api/v1/integrations/calendly/callback: post: tags: - calendly summary: Complete Calendly authorization description: >- **Authorization:** Requires an Admin or Owner role in the requested workspace. Exchange a pending authorization result and discover workspace Calendly tools. operationId: complete_calendly_api_v1_integrations_calendly_callback_post parameters: - description: >- 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. in: header name: X-VOAI-ORGANIZATION-ID required: false schema: anyOf: - type: string - type: 'null' description: >- 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. title: X-Voai-Organization-Id requestBody: content: application/json: schema: $ref: '#/components/schemas/CalendlyCallback' example: state: state-from-your-pending-authorization code: code-returned-by-calendly required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CalendlyStatus' description: Successful Response '400': description: Invalid request or missing/invalid workspace header with an API key. '401': description: Missing, invalid, or expired credential. '403': description: >- The account lacks access to the workspace, resource, or required role. '404': description: Not found '409': description: >- Reconnect is required or a newer connection attempt replaced this attempt. '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error '502': description: Calendly could not complete the request. security: - LabsAuth: [] - LabsApiKey: [] components: schemas: CalendlyCallback: properties: code: anyOf: - maxLength: 4096 type: string - type: 'null' title: Code description: >- Authorization code returned by Calendly after consent; omit when sending an authorization error. error: anyOf: - maxLength: 256 type: string - type: 'null' title: Error description: >- Provider authorization error, such as access_denied, when consent did not complete. state: maxLength: 256 minLength: 1 title: State type: string description: >- Single-use state returned by the pending authorization attempt for this user and workspace. required: - state title: CalendlyCallback type: object CalendlyStatus: properties: account_name: anyOf: - type: string - type: 'null' title: Account Name description: Connected account display name; may remain after disconnect. can_manage: title: Can Manage type: boolean description: >- Whether the caller is an Admin or Owner who can change this workspace connection. integration_id: anyOf: - type: string - type: 'null' title: Integration Id description: >- Workspace integration identifier, or null before a connection record exists. last_synced_at: anyOf: - type: number - type: 'null' title: Last Synced At description: Unix timestamp in seconds of the last successful discovery, or null. state: enum: - not-connected - connected - reconnect-required - discovery-failed title: State type: string description: >- Connection readiness. Inspect this field even after HTTP 200; cached tools may remain while the connection is unusable. tool_uuid: anyOf: - type: string - type: 'null' title: Tool Uuid description: >- Linked managed tool group UUID. Select its tools for agents explicitly. tools: items: $ref: '#/components/schemas/CalendlyTool' title: Tools type: array description: >- Cached provider tool catalog. Use only while state is connected; discovery is not permission to execute every tool. required: - state - can_manage title: CalendlyStatus type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object CalendlyTool: properties: annotations: additionalProperties: true title: Annotations type: object description: Provider behavior hints; these do not grant execution permission. description: title: Description type: string description: Provider description of the tool. input_schema: additionalProperties: true title: Input Schema type: object description: JSON Schema for the provider tool arguments. name: title: Name type: string description: Provider tool name used for agent tool selection. title: title: Title type: string description: Provider display title, falling back to the tool name. required: - name - title - description - input_schema - annotations title: CalendlyTool type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object securitySchemes: LabsAuth: description: >- 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. scheme: bearer type: http LabsApiKey: description: >- Bandwidth Labs API key. Also send `X-VOAI-ORGANIZATION-ID` with a positive local workspace ID belonging to the key owner. Access follows the owner's current workspace role. Do not also send a bearer token. API keys cannot access bearer-only or Labs `super_user` operations. in: header name: X-BW-LABS-AGENTS-API-KEY type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.