How to give an AI agent read access to your availability (without your calendar)

Give the key read scope only, and give it to a single endpoint: an availability API, not the calendar itself. A read-scoped key returns busy/free blocks — start time, end time, nothing else — and you can revoke it in one click. The alternative most integrations default to, a full OAuth calendar grant, hands the agent every event it can see, forever, until you remember to go find the connected-apps list and pull it. For an agent whose only job is answering “when are you free?”, that's a lot of standing access for a small question. This guide covers why the trust model matters, the alternatives, and how to wire up a scoped key against BusyBoard's API.

Why a full calendar grant is the wrong shape for an agent

A calendar OAuth grant is built for a human's calendar app: broad, long-lived, and scoped to “read and write everything.” That's reasonable when a person is looking at their own screen. It's a different proposition when the consumer is an agent running unattended, possibly logging its tool calls, possibly forwarding context to a model you don't control. Once that grant exists, every meeting title, attendee list, and location the agent's calendar tool touches is fair game for it to read, summarize, or pass along — even though the actual task was a single yes/no question about a time slot.

The fix isn't a smarter prompt telling the agent to ignore event details. It's not giving it the details in the first place. An availability layer that only ever returns busy/free is a narrower grant by construction — there's no title field for the agent to read, because the API response doesn't have one.

What people do instead of a full grant

• A static free/busy export.Export an .ics feed once and hand the URL to the agent. It's narrow in scope, but it's a snapshot — it goes stale the moment your calendar changes, and an agent working from a stale file will confidently propose a time you've since booked over.
• A hand-maintained list.Some people keep a note of “generally free Tue/Thu afternoons” for an assistant to reference. It costs nothing to set up and is wrong the first week your schedule changes, because nothing keeps it in sync with the calendar.
• A scoped availability API. The agent calls a live endpoint, gets current busy/free for a date range, and the scope on the key limits what it can ever ask for. No file to go stale, no manual upkeep, and the access is read-only by default.

The third option is the only one that's both current and narrow. This is what BusyBoard's API is for.

Create a read-only key

In BusyBoard, open Settings → API and create a key. New keys default to read scopes — read:freebusy and read:people — which are free on any plan. The key starts with bb_live_, is shown once, and is stored hashed on BusyBoard's side, so there's no plaintext copy sitting in a database for anyone to leak.

With the key in hand, a read request against your own availability looks like this:

curl "https://busyboard.app/api/v1/availability?startDate=2026-09-15&endDate=2026-09-19" \
  -H "Authorization: Bearer bb_live_your_key_here"

startDate and endDate are read as full calendar days in your own timezone — the one set on your account, not UTC. Leave off userIds and it defaults to you; pass a comma-separated list of user IDs to read teammates' availability the same way, subject to the same dual-detail rule described below (people you are connected to through a share link are addressed separately, on the find-time endpoint). The response is a flat list of busy blocks:

{
  "data": [
    {
      "id": "blk_9f2a",
      "userId": "5b1e...",
      "startTime": "2026-09-15T13:00:00Z",
      "endTime": "2026-09-15T13:30:00Z",
      "isAllDay": false,
      "responseStatus": "accepted",
      "mergedCount": 1
    }
  ],
  "pagination": { "total": 14, "limit": 50, "offset": 0, "hasMore": false }
}

responseStatus (accepted, tentative, needsAction) is included on your own blocks only — it's useful context on your own calendar and meaningless noise on someone else's. What the response never contains, for you or anyone else: a title, a description, attendees, or a location. Those fields don't exist in the API's data model, so there's nothing for a bug or a careless prompt to leak — the boundary is structural, not a filter applied after the fact.

Where the Pro write scope comes in

Reading availability — your own, a teammate's, or an external connection's — only ever needs the free read scopes. If the agent should also be able to act on what it finds, that's a separate, explicit scope: propose:booking, which requires a Pro plan and lets the key call POST /booking-proposals. A proposal doesn't book anything directly — it lands in the target's approval queue exactly like a request from a human visiting their share page, and only confirms outright if that share has auto-accept turned on. Every proposal call also requires a caller-generated idempotencyKey, so an agent that retries after a timeout can't accidentally create two proposals for the same slot — the replay returns the original outcome instead. Keeping read and write on separate scopes means you can hand an agent enough access to answer questions without ever giving it the power to put something on someone's calendar.

MCP or REST?

Both sit on the same key, the same scopes, and the same rate limits — the choice is about the client, not the access model. If you're building your own integration, a script, or a server-side agent that calls tools directly, the REST endpoints above are the more direct fit. If your agent runs inside a client that speaks MCP — Claude Desktop, Claude Code, Cursor, or the Messages API pointed at a remote server — BusyBoard's hosted MCP endpoint gives it the same read tools (plus proposing, on a Pro key) with nothing to install: paste the endpoint and your key into the client's config and it's live. The AI assistant setup guide walks through that config, and the full tool list and rate limits are in the agents documentation.