Calendly Port

Purpose

This is the Harbor reference integration for the Calendly API.

Use it when:

• building Calendly actions in Harbor
• extending the Dock / Hub Calendly entry
• teaching Codex or OpenClaw how to map bounded event type discovery, scheduled-event reads, and explicit cancellation into Harbor Ports and Harbor Actions without turning Harbor into a full scheduling proxy

Harbor Port worksheet

Product

• Product: Calendly API
• Publisher slug: calendly
• Publisher name: Calendly
• Category: Work Management
• Tags: calendly, scheduling, meetings, event-types, calendar

Safe Harbor Port metadata

• Kind: http_api
• Label: Calendly API
• Description: Calendly API connection managed locally through Harbor.
• Base URL: https://api.calendly.com
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Calendly personal access tokens and OAuth access tokens should both stay local to Harbor Node.

Harbor action design notes

Calendly is a good Harbor fit when the starter set stays on bounded scheduling reads and one clearly reviewable mutation.

Good Harbor Calendly starter actions:

• one bounded GET route for event type discovery
• one bounded GET route for scheduled events with explicit organization and time filters
• one reviewable POST route for canceling a scheduled event by UUID
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for cancel-event
• resultMode: "json_summary" for all starter actions

Avoid for now:

• arbitrary scheduling passthrough or embedded booking flows
• exposing broader invitee creation or rescheduling surfaces in the first pass
• destructive or bulk calendar operations beyond one explicit cancellation route
• assuming Harbor should discover every Calendly principal automatically

Starter Calendly actions

Automatic read actions

• list-event-types -> GET /event_types
• list-scheduled-events -> GET /scheduled_events

Approval-friendly write actions

• cancel-event -> POST /scheduled_events/{eventUuid}/cancellation

Why these actions

These routes fit Harbor's current safe model because they:

• use standard Bearer auth with no extra static headers
• stay on stable REST resources under one fixed Calendly API base URL
• force reads through explicit organization or user URI inputs instead of broad hidden traversal
• keep the only mutation in the starter set deliberate and operator-reviewable

Action Model notes

At execution time, callers supply values by location:

• input.query.organization or input.query.user, plus optional pagination and activity filters, for list-event-types
• input.query.organization, plus optional status, time, and pagination filters, for list-scheduled-events
• input.path.eventUuid and input.body for cancel-event

Example event type request:

{
  "query": {
    "organization": "https://api.calendly.com/organizations/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "active": true,
    "count": 20
  }
}

Example scheduled event request:

{
  "query": {
    "organization": "https://api.calendly.com/organizations/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "status": "active",
    "min_start_time": "2026-03-28T00:00:00Z",
    "max_start_time": "2026-04-04T00:00:00Z",
    "count": 20
  }
}

Example cancellation request:

{
  "path": {
    "eventUuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  },
  "body": {
    "reason": "Operator-approved cancellation from Harbor"
  }
}

For cancel-event, keep the body bounded to the cancellation payload you intentionally want Harbor workflows to supply.

Safety note for cancellation

The two read actions stay automatic because they are bounded reads. cancel-event stays on require_approval because it mutates a live scheduling record, can notify participants, and can create real-world impact from a legitimate environment.

Suggested operator workflow

1. Import the Calendly Dock entry from Dock / Hub.
2. Configure the local Calendly bearer token in Harbor Node.
3. Capture the organization URI or user URI from your Calendly account context.
4. Use list-event-types to confirm the scheduling surface you need.
5. Use list-scheduled-events with explicit time windows before approving a cancellation.
6. Keep cancel-event on require_approval unless there is a very clear local policy reason not to.

Suggested agent workflow

1. Inspect the existing Calendly Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed Calendly routes only when they remain bounded and reviewable.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored Calendly token
• widen the starter set into generic booking or full scheduling administration
• add destructive or bulk meeting mutations without review
• assume Harbor should infer tenant identity without explicit operator input

Current update strategy

For now, Calendly updates are manual:

• update the Dock / Hub Calendly integration document in apps/hub/catalog/integrations/calendly/calendly-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Official reference starting points

• Calendly developer home: https://developer.calendly.com/
• Calendly authentication with personal access tokens: https://developer.calendly.com/how-to-authenticate-with-personal-access-tokens
• Calendly API reference entry point: https://developer.calendly.com/api-docs