Skip to content

Document encrypted calendar token storage #147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Document encrypted calendar token storage #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
00a2fe3
Update calendar and invite API specifications
mintlify[bot] Mar 25, 2026
dbf6685
Add encrypted token storage docs and OAuth state expiry details
mintlify[bot] Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 36 additions & 28 deletions api-reference/calendar.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,26 @@

Connect a Google Calendar account and manage events, check availability, and schedule directly through the API.

<Note>Most calendar endpoints require a connected Google Calendar account. Use the [connect flow](#connect-calendar) to authorize access before calling event endpoints.</Note>
<Note>All calendar endpoints require an authenticated session. The user is identified from the session automatically — you do not pass a `userId` parameter.</Note>

Check warning on line 10 in api-reference/calendar.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/calendar.mdx#L10 

Did you really mean 'userId'?

<Note>Most calendar endpoints also require a connected Google Calendar account. Use the [connect flow](#connect-calendar) to authorize access before calling event endpoints.</Note>

## Base URL

```
https://agentbot.raveculture.xyz/api/calendar
```

## Authentication

All calendar endpoints require a valid NextAuth session. Requests without an active session receive a `401 Unauthorized` response (or a redirect to `/login` for browser-based flows).

The authenticated user's identity is derived from the session. You do not need to include a `userId` parameter in any request.

## Token storage

Calendar tokens (access and refresh tokens) are encrypted at rest using AES-256-GCM before being persisted to the database. Tokens are never stored in plaintext.

Check warning on line 28 in api-reference/calendar.mdx

View check run for this annotation

Mintlify / Mintlify Validation (raveculture) - vale-spellcheck

api-reference/calendar.mdx#L28 

Did you really mean 'plaintext'?

## Connect calendar

```http
Expand All @@ -28,7 +40,6 @@
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `action` | string | Yes | Must be `connect` |
| `userId` | string | Yes | Your user identifier |

### Response

Expand All @@ -44,6 +55,7 @@

| Code | Description |
|------|-------------|
| 401 | Not authenticated (no active session) |
| 400 | Invalid action |

## OAuth callback
Expand All @@ -59,17 +71,18 @@
| Parameter | Type | Description |
|-----------|------|-------------|
| `code` | string | Authorization code provided by Google |
| `state` | string | The `userId` passed during the connect flow |
| `state` | string | HMAC-signed state token generated during the connect flow. Contains the user ID and a timestamp, verified on callback. Expires after 10 minutes. |
| `error` | string | Error code if the user denied access or an error occurred |

### Behavior

On success, this endpoint:

1. Exchanges the authorization code for access and refresh tokens.
2. Retrieves the user's primary calendar ID and timezone.
3. Stores the connection for future API calls.
4. Redirects to `/dashboard/calendar?connected=true`.
1. Verifies the HMAC-signed state parameter and checks it has not expired.
2. Exchanges the authorization code for access and refresh tokens.
3. Retrieves the user's primary calendar ID and timezone.
4. Encrypts and persists the tokens to the database (AES-256-GCM).
5. Redirects to `/dashboard/calendar?connected=true`.

### Error redirects

Expand All @@ -90,6 +103,8 @@

Redirects the browser directly to the Google OAuth consent screen. This is an alternative to the POST-based connect flow — use it when you want a simple link-based authorization.

Requires an active session. If the user is not authenticated, this endpoint redirects to `/login`.

### Query parameters

| Parameter | Type | Required | Description |
Expand All @@ -99,17 +114,16 @@
## List events

```http
GET /api/calendar?action=list&userId={userId}
GET /api/calendar?action=list
```

Returns calendar events within a date range.
Returns calendar events within a date range. The user is identified from the session.

### Query parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | Yes | Must be `list` |
| `userId` | string | Yes | Your user identifier |
| `start` | string | No | ISO 8601 start date. Defaults to now. |
| `end` | string | No | ISO 8601 end date. Defaults to 30 days from now. |

Expand All @@ -134,22 +148,21 @@

| Code | Description |
|------|-------------|
| 401 | Calendar not connected |
| 401 | Not authenticated or calendar not connected |

## Check availability

```http
GET /api/calendar?action=availability&userId={userId}
GET /api/calendar?action=availability
```

Returns available and busy time slots for a given date. Slots are one hour each, from 09:00 to 23:00.
Returns available and busy time slots for a given date. Slots are one hour each, from 09:00 to 23:00. The user is identified from the session.

### Query parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | Yes | Must be `availability` |
| `userId` | string | Yes | Your user identifier |
| `date` | string | No | Date in `YYYY-MM-DD` format. Defaults to today. |

### Response
Expand All @@ -171,22 +184,21 @@

| Code | Description |
|------|-------------|
| 401 | Calendar not connected |
| 401 | Not authenticated or calendar not connected |

## Create event

```http
POST /api/calendar
```

Creates a new calendar event.
Creates a new calendar event. The user is identified from the session.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `action` | string | Yes | Must be `create-event` |
| `userId` | string | Yes | Your user identifier |
| `title` | string | Yes | Event title |
| `start` | string | Yes | ISO 8601 start time |
| `end` | string | Yes | ISO 8601 end time |
Expand All @@ -199,7 +211,6 @@
```json
{
"action": "create-event",
"userId": "user_123",
"title": "DJ Set @ Warehouse",
"start": "2026-03-28T22:00:00Z",
"end": "2026-03-29T02:00:00Z",
Expand Down Expand Up @@ -227,7 +238,7 @@

| Code | Description |
|------|-------------|
| 401 | Calendar not connected |
| 401 | Not authenticated or calendar not connected |
| 500 | Internal error |

## Update event
Expand All @@ -236,14 +247,13 @@
POST /api/calendar
```

Updates an existing calendar event. Only the fields you include are changed.
Updates an existing calendar event. Only the fields you include are changed. The user is identified from the session.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `action` | string | Yes | Must be `update-event` |
| `userId` | string | Yes | Your user identifier |
| `eventId` | string | Yes | ID of the event to update |
| `title` | string | No | Updated event title |
| `description` | string | No | Updated description |
Expand All @@ -264,7 +274,7 @@

| Code | Description |
|------|-------------|
| 401 | Calendar not connected |
| 401 | Not authenticated or calendar not connected |
| 500 | Internal error |

## Delete event
Expand All @@ -273,14 +283,13 @@
POST /api/calendar
```

Deletes a calendar event.
Deletes a calendar event. The user is identified from the session.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `action` | string | Yes | Must be `delete-event` |
| `userId` | string | Yes | Your user identifier |
| `eventId` | string | Yes | ID of the event to delete |

### Response
Expand All @@ -295,7 +304,7 @@

| Code | Description |
|------|-------------|
| 401 | Calendar not connected |
| 401 | Not authenticated or calendar not connected |
| 500 | Internal error |

## Quick add
Expand All @@ -304,14 +313,13 @@
POST /api/calendar
```

Creates an event from a natural language string using Google Calendar's quick-add feature.
Creates an event from a natural language string using Google Calendar's quick-add feature. The user is identified from the session.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `action` | string | Yes | Must be `quick-add` |
| `userId` | string | Yes | Your user identifier |
| `text` | string | Yes | Natural language event description (for example, `"Meeting with Sarah tomorrow at 3pm"`) |

### Response
Expand All @@ -327,5 +335,5 @@

| Code | Description |
|------|-------------|
| 401 | Calendar not connected |
| 401 | Not authenticated or calendar not connected |
| 500 | Internal error |
Loading