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.
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.
| Scope | Label | What it allows |
|---|---|---|
read_freebusy | View calendar availability | Check whether a slot is available without seeing event details. Used for scheduling assistants and time-pickers. |
read_events | Read events | See full event metadata: title, attendees, meeting class, priority. Used for context-aware agents and conflict explainers. |
create_holds | Create holds | Reserve a slot temporarily while a booking is being confirmed. Used for multi-party schedulers and poll-based flows. |
create_bookings | Create bookings | Write a confirmed event to the calendar owner's calendar. Used for sales bots, recruiting agents, focus-time schedulers. |
preempt | Preempt | Displace a lower-priority booking when a higher-priority one arrives. Used for executive assistants and high-priority meeting handlers. |
You can update an agent's permissions after creation via PATCH /v1/agents/{id}. Changes take effect on the next request — in-flight requests are not affected.
Scoping to calendar owners
An agent's allowed owners list is enforced at the API level. If sales-bot tries to book on [email protected]'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.