Register an agent
Agents are the identity Openavail uses to track which system made each booking request.
What is an agent
An agent is a registered identity in Openavail that corresponds to one of your AI systems (a sales bot, a recruiting assistant, a personal AI, etc.). Each agent has:
- A display name and optional description
- A set of API keys
- A priority class (used to resolve conflicts between agents of the same meeting class)
- A scope: which calendar owners this agent is permitted to touch
Agents never log into the dashboard. They authenticate via API keys.
Start with Agent Test Flight
For first setup, use Agent Test Flight before creating production API keys.
Previewing or running Agent Test Flight creates or reuses a normal Test Agent with only read_freebusy and create_booking_proposals. It proves the approval path without giving an agent direct booking permissions, and the internal Test Flight credential is not shown as a reusable key. Skipping Agent Test Flight does not create a Test Agent or credential.
After the flow, register a separate production agent for real integrations. Test Flight agents use internal credentials only and cannot mint normal API keys.
Create an agent
In the dashboard, go to Agents → New agent. Provide:
| Field | Description |
|---|---|
| Name | Human-readable identifier shown in audit logs |
| Default meeting class | The class used when the agent doesn't specify one |
| Allowed owners | Calendar owners this agent may book on behalf of |
After creation, go to the agent's detail page and create an API key. Store it immediately — it is shown only once.
Permission scopes
Permissions are granted at agent registration and enforced on every request. Request only what your agent needs — the principle of least privilege applies.
New agents should start in approval mode with read_freebusy and
create_booking_proposals. Add auto-booking scopes only after the agent has earned trust. Add
sensitive scopes only when the agent truly needs them.
| Scope | Label | What it allows |
|---|---|---|
read_freebusy | View calendar availability | Search for candidate times without reserving them. Used for scheduling assistants and time-pickers. |
create_booking_proposals | Propose bookings | Create approval-first booking proposals. The calendar owner approves or rejects before anything is written. |
read_events | View event details | See booking titles, descriptions, and attendees in Openavail responses. Used for trusted context-aware agents. |
create_holds | Reserve time slots | Create short-lived candidate or window holds. Used for multi-party schedulers and poll-based flows. |
create_bookings | Book meetings | Confirm a held time and write the approved booking. Used for sales bots, recruiting agents, focus-time schedulers. |
preempt | Displace lower-priority bookings | Displace a lower-priority booking when a higher-priority one arrives. Used for executive assistants and high-priority meeting handlers. |
cancel_human_events | Cancel human-created events | Cancel bookings that the calendar owner created directly in their calendar (not via Openavail). Without this, agents can only cancel bookings they or another agent created through Openavail. Used for personal assistant agents that need full calendar control. |
You can update an agent's permissions after creation via PATCH /v1/agents/{id}. API-key agents use the new permissions on the next request; in-flight requests are not affected. Hosted MCP connections may need a fresh OAuth login before newly granted tools are usable in the client, while permission removals and revocations fail closed on the server immediately.
Scoping to calendar owners
An agent's allowed owners list is enforced at the API level. If sales-bot tries to book on ceo@acme.com's calendar and the CEO is not in its allowed list, the request is rejected with 403 Forbidden.
This prevents a misconfigured or compromised agent from touching calendars it shouldn't know about.
Agent status
Agents can be active or disabled. Disabling an agent immediately rejects all new requests from its keys. Existing holds made by that agent expire normally — they are not force-cancelled.
You can re-enable a disabled agent at any time. Its keys remain valid.