Google Calendar

Beta

This connector is in beta. It works end to end and is safe to use on real calendars, but the surface can still change before general availability, so do not pin automation to exact tool names or response shapes yet.

How it works

Connect a Google account once, choose which agents may use it, and give each one a read or a write grant. During a call the agent can check availability and offer open times, and with write it can also book, reschedule and cancel, all as ordinary events you can see in Google Calendar. The grant is the whole story, and everything below follows from it.

Connect a calendar

Connecting is an OAuth consent flow, so it needs a browser once: the calendar owner approves the access at Google. Aethex gives you the URL to send them to, and you never see their credentials. The authorize and grant calls need an API key with integrations:write; reading connections needs integrations:read.

1. 01

   Ask for a consent URL

   Returns the Google URL to open. It is single-use and valid for 10 minutes, so generate it when the person is ready to click.

   bash

   curl -X POST https://api.aethexai.com/api/v1/integrations/google_calendar/authorize \
     -H "X-API-Key: $AETHEX_API_KEY"
   
   # { "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?..." }

2. 02

   Open it and approve

   The calendar owner signs in at Google and approves the two permissions. Google redirects back to Aethex, which finishes the exchange. Confirm the result from the API, not from where the browser lands.

3. 03

   Confirm the connection

   The connection is live once it appears with status: active. Note its id, since the grant and disconnect calls both take it. agents comes back empty, which means no agent can use it yet.

   bash

   # Keep the id: the grant and disconnect calls below both take it.
   CONNECTION_ID=$(curl -s https://api.aethexai.com/api/v1/integrations \
     -H "X-API-Key: $AETHEX_API_KEY" \
     | jq -r '.data[] | select(.provider == "google_calendar") | .id')

Grant agents access

A connected calendar belongs to the account, not to one agent, so it reaches an agent only when you grant it. Give an agent read to check availability and offer times, or write to also book, reschedule and cancel. The grant call is declarative: it replaces the whole set, and an empty list revokes everyone. Grants are read when a call starts, so a change applies to the next call, not one already in progress. Reschedule and cancel act only on a meeting the agent booked in the same call, since they need its event id and the agent cannot search the calendar for one it did not create.

curl -X PUT https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID/agents \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agents": [
      { "agent_id": "6b1e...", "access": "write" },
      { "agent_id": "9d02...", "access": "read"  }
    ]
  }'

The access being approved

Connecting asks Google for exactly two permissions, and nothing else. The broader scope that could read your calendar list, its settings, or who it is shared with is a different Google scope, and Aethex does not request it.

Status codes worth knowing

The ones you are most likely to meet while wiring this up. 401 and 403 can come from any call; 404 and 409 come from the grant call; 422 and 503 come from authorize.

Disconnect

Deletes the connection and the stored access at once, including on calls in progress, so the next calendar action in a live call fails. It does not touch the calendar itself, so booked meetings stay where they are. Disconnecting is idempotent and returns 204 whether the connection was active, already gone, or never existed. You can also revoke access from the Google account's own third-party settings; the connection then turns to status: error on its next token refresh.

curl -X DELETE https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID \
  -H "X-API-Key: $AETHEX_API_KEY"

# 204 No Content

If something does not work

The handful of things that usually explain a calendar that looks broken.