Token Permissions

Access tokens can be configured with fine-grained permissions that control what data is visible and what operations are allowed.

Master Access Level

Controls the overall access tier for the token.

Value	Description
`free_busy_only`	Can only see free/busy periods — no event details
`view_only`	Can see all event data but cannot create/edit/delete
`view_filtered`	Can see only fields specified in visibleFields
`full_access`	Full read/write access (operations controlled by allowedOperations)

Visible Fields

When masterAccessLevel is view_filtered, only these fields are included in event responses. Pass "all" to include everything.

Value	Description
`title`	Event title/summary
`location`	Event location
`description`	Event description/notes
`attendees`	List of attendees
`times`	Start and end times
`status`	Event status (confirmed, tentative, cancelled)
`labels`	Event labels/tags
`join_url`	Video conference join URL
`organizer`	Event organizer
`all`	All fields (shorthand)

Allowed Operations

When masterAccessLevel is full_access, these control which write operations are permitted.

Value	Description
`respond_to_event`	Accept, decline, or tentatively accept invitations
`edit_title`	Modify event titles
`edit_location`	Modify event locations
`edit_description`	Modify event descriptions
`edit_attendees`	Add or remove attendees
`edit_times`	Change event start/end times
`create_events`	Create new events
`delete_events`	Delete events
`all`	All operations (shorthand)

Timeframe Restrictions

Limit the time window a token can access.

Field	Type	Description
timeframePastDays	int?	How many days into the past. null = unlimited
timeframeFutureDays	int?	How many days into the future. null = unlimited

Tip

Example: timeframePastDays: 30, timeframeFutureDays: 60 means the token can only access events from 30 days ago to 60 days from now.

Email Access Enabled

The master gate for email access. When false (default), all email endpoints return access denied. Email permissions are independent from calendar permissions.

Value	Description
`false`	Email access disabled (default)
`true`	Email access enabled — specific operations controlled by allowedEmailOperations

Warning

Email access is disabled by default. You must set emailAccessEnabled: true before the token can use any email endpoints.

Visible Email Fields

Controls which fields are included in email responses. Uses bitflag-based filtering for O(1) performance. Pass "all" to include everything. When a field is not visible, it is returned as null.

Value	Description
`subject`	Email subject line
`from`	Sender information
`recipients`	To, Cc, and Bcc recipients (toggled together)
`body`	Full email body content
`body_preview`	Short body preview/snippet
`attachments`	Attachment metadata
`timestamp`	Sent and received timestamps
`labels`	Email labels/categories
`all`	All fields (shorthand) — default

Allowed Email Operations

Controls which email operations are permitted. Pass "all" to allow everything. Default: view_email, search_emails, view_thread (read-only).

Value	Description
`view_email`	View individual emails
`search_emails`	Search and list emails
`view_thread`	View email threads
`send_email`	Send new emails
`reply_to_email`	Reply to existing emails
`forward_email`	Forward emails to other recipients
`delete_email`	Delete (trash) emails
`mark_as_read`	Mark emails as read/unread
`apply_labels`	Add or remove labels/categories
`all`	All operations (shorthand)

Access Rules & Linked Resources

Access Rules are per-contact or per-domain rules that override the master access level for specific email addresses or domains. See Access Rules Management.

Linked Resources — Tokens must have at least one linked resource (calendar) to access data. See Resource Links Management.

Avatars

Tokens can be assigned an avatar for visual identification.

Value	Description
`general`	Default/generic avatar
`openclaw`	OpenClaw avatar
`claude`	Claude (Anthropic) avatar
`openai`	OpenAI avatar
`gemini`	Gemini (Google) avatar

GET/api/auth/token/{tokenId}/permissionsBearer / JWT

Get Token Permissions

Returns the permission settings for a specific access token.

Path Parameters

Parameter	Type	Description
tokenId	int	Access token ID

Response 200 OK

{ 
  "keyId": 42, 
  "title": "My Integration Key", 
  "operatorId": "550e8400-e29b-41d4-a716-446655440000", 
  "masterAccessLevel": "view_filtered", 
  "visibleFields": ["title", "times", "attendees"], 
  "allowedOperations": [], 
  "emailAccessEnabled": true, 
  "visibleEmailFields": ["subject", "from", "recipients", "body_preview", "timestamp"], 
  "allowedEmailOperations": ["view_email", "search_emails", "view_thread"], 
  "timeframePastDays": 30, 
  "timeframeFutureDays": 60, 
  "timeframeDescription": "Last 30 days to next 60 days", 
  "accessRules": [ 
    { 
      "id": 1, 
      "accessTokenId": 42, 
      "identifierType": "domain", 
      "identifier": "competitor.com", 
      "accessLevel": "block", 
      "priority": 10, 
      "description": "Block competitor domain", 
      "createDate": "2026-02-01T10:00:00Z" 
    } 
  ], 
  "linkedResources": [ 
    { "resourceId": "aaa-bbb-ccc", "title": "Primary Calendar" } 
  ], 
  "hasLinkedResources": true, 
  "lastUpdated": "2026-02-01T10:00:00Z" 
}

PATCH/api/auth/token/{tokenId}/permissionsBearer / JWT

Update Token Permissions

Updates the permission settings for a specific access token. All fields are optional — only provided fields are updated.

Request Body (all optional)

Field	Type	Description
masterAccessLevel	string	New access level
visibleFields	string[]	New visible fields list
allowedOperations	string[]	New allowed operations list
timeframePastDays	int	New past days limit
timeframeFutureDays	int	New future days limit
emailAccessEnabled	bool	Enable/disable email access
visibleEmailFields	string[]	New visible email fields list
allowedEmailOperations	string[]	New allowed email operations list

{ 
  "masterAccessLevel": "view_only", 
  "visibleFields": ["title", "times"], 
  "allowedOperations": ["respond_to_event"], 
  "timeframePastDays": 14, 
  "timeframeFutureDays": 30, 
  "emailAccessEnabled": true, 
  "visibleEmailFields": ["all"], 
  "allowedEmailOperations": ["view_email", "search_emails", "view_thread", "send_email", "reply_to_email"] 
}