Agent access
Give a script or automation its own token to create rooms and schedules on your behalf.
Agent access tokens let something other than a person with a browser create rooms and build schedules in your account — a script, a no-code automation tool (Zapier, n8n, Make), or a custom integration you have written yourself. It authenticates over a small REST API instead of a login session.
Find it at Agent access in account settings, or /settings/agent-access.
What this is, and is not, for
This is a credential for software you control — a script, a no-code automation tool, or Claude connected via MCP, which uses this same token through its connector's own authentication field rather than a chat message. There is no ChatGPT connector yet: ChatGPT's custom connectors only support no-auth or OAuth, not a pasted token, so that integration is a deliberate, not-yet-built follow-up rather than an oversight.
Do not paste a raw token into a chat message. Doing so puts your credential in that provider's conversation history and logs, which is exactly the exposure this feature's token hashing is designed to prevent on our side. Give the token to a script's environment variables, an automation platform's own credential store, or a custom integration's secrets manager — never to a chat message.
Creating a token
In the Create a token form, set:
- Name — anything that reminds you what will use it, for example "Zapier automation" or "Nightly schedule importer".
- Scopes — which actions the token may perform (see the table below). At least one is required.
- Expires — 30 days, 90 days, 1 year, or no expiry.
Click Create token.
Scopes
Four scopes exist, but only two currently do anything, because only two REST endpoints exist to authorize:
| Scope | Label in the form | What it allows |
|---|---|---|
rooms:create | Create rooms | Create a new room — works today |
schedules:create | Create schedules | Add timers to a room the token can access — works today |
rooms:read | Read rooms | Reserved for a future rooms-lookup endpoint — nothing calls this yet |
schedules:read | Read schedules | Reserved for a future schedule-lookup endpoint — nothing calls this yet |
Selecting a read scope does no harm, but it does not unlock anything either —
there is no endpoint yet for it to authorize. Stick to rooms:create and
schedules:create unless you are deliberately preparing for a later release.
Expiry
Choose the shortest expiry that is still practical for whatever holds the token. An expired token stops working the same way a revoked one does; the only difference is that expiry happens on its own, without anyone clicking anything.
The token is shown once
When you create a token, a panel shows its full raw value — the only time it is ever displayed. Copy it now. Tamora stores only a cryptographic hash of the value, so if you close the panel or reload the page without copying it, nobody — including us — can recover it. Your only options at that point are to rotate the token or create a new one.
Rotating works the same way: the new value is shown exactly once, at the moment you rotate.
The panel's Done button stays disabled until you tick I've saved this token, and pressing Escape or clicking outside the panel does nothing. This is deliberate, so the panel cannot be dismissed by accident before you have copied the value.
Revoking and rotating
Every active token in the list has Rotate and Revoke controls.
- Revoke stops the token working immediately. A confirmation dialog names the token first, because this cannot be undone — anything already using it starts failing right away. A revoked token stays in the list, shown as revoked, rather than disappearing, so its history stays visible in Agent activity below.
- Rotate replaces a token's value while keeping its name, scopes, and expiry. The old value stops working the moment you rotate, and the new value is revealed once, exactly as at creation. Use this instead of revoking and recreating when you only need to swap the secret a script uses, without reconfiguring anything else about it.
What the two endpoints do
Both endpoints are called with an Authorization: Bearer header carrying the raw
token — for example, Authorization: Bearer et_pat_2f6a9c… — plus a JSON request
body, and both return the created resource on success, as an HTTP 201. This
section describes them at the level someone deciding whether to use this feature
needs; it is not a full API reference.
Creating a room — POST /api/v1/rooms
Requires the rooms:create scope. Has the same effect as clicking + New room
on the dashboard.
| You send | Type |
|---|---|
title | text |
timezone | an IANA name, e.g. Europe/London |
The response carries the new room's id, title, timezone, and created_at.
If your account is on the free tier and already has a room, this fails with an upgrade-required error instead of creating a second one — the same limit the dashboard itself enforces.
Adding a schedule — POST /api/v1/rooms/:roomId/schedule
Requires the schedules:create scope. Put the room's id from the step above
where :roomId appears in the URL.
| You send | Type |
|---|---|
items | a list of timers to create |
each item's title | text |
each item's duration_sec | whole number of seconds |
each item's speaker / notes | text, optional |
The response carries the timers that were created. The same limits as CSV import apply: up to 500 items per request, and each duration is clamped to between 1 second and 24 hours.
A token can never be pointed at a room it does not own by supplying a different id anywhere in the request — access is always resolved from the token itself, never from anything in the request body.
Retrying safely
If your automation might retry a request after a timeout or a dropped response,
send an Idempotency-Key header with a value unique to that one logical request.
A retried request carrying the same key returns the original result instead of
creating a second room or schedule.
Agent activity
The Agent activity list on the same settings page shows recent actions taken through a token — a created room, a created schedule, or a failed or unauthorized attempt — each with a timestamp and a result. It only shows activity for your own tokens, is limited to the most recent entries, and has no filter or export control. Check it whenever a token has done something you did not expect.
Treat the token like a password
A raw token grants whatever its scopes allow, to whoever holds it, with no login step in between. If you suspect one has leaked — committed to a public repository, pasted somewhere it should not have been, sent to the wrong person — revoke it immediately rather than waiting to investigate first. Agent activity keeps a record of what the token did before you revoked it, so you can review that afterwards without leaving the exposure open in the meantime.
Related
- Team management — the team a token's rooms and schedules belong to
- CSV import — the row cap and duration clamp the schedule endpoint shares with CSV import
- Controller — where a room or schedule created by a token appears, exactly like one created by hand