Every request to the public API must carry an Authorization: Bearer tok_* header. The token is a scoped, workspace-bound Token you mint
from the workspace settings UI or the Webhooks API.
Token shape
A token looks like tok_… and is paired with a list of scopes. A
typical setup has two tokens per workspace:
- Read token with
moments.read,collections.read,tags.read,workspaces.readfor workspace-level consumers. - Write token with
moments.write,collections.write,tags.write,webhooks.writefor integrations that mutate state.
Available scopes
The 16 scopes the API understands (no others are accepted):
| Scope | Allows |
|---|---|
moments.read / moments.write | List, create, update, archive moments. |
collections.read / collections.write | Read and mutate collections. |
tags.read / tags.write | Read and mutate tags. |
moments.read / moments.write | Inspect and update Tracking schedules. |
webhooks.read / webhooks.write | Subscribe to events. |
workspaces.read | Read the audit log and the workspace itself. |
apis.read / apis.write | Reserved — manage API tokens. |
apis.all | Reserved — super-admin scope. |
A 403 with error.code = "forbidden" is returned when a token tries
to call an endpoint it doesn't have scope for.
Sending a token
| 1 | GET /v1/moments?page=1&pageSize=20 HTTP/1.1 |
| 2 | Host: api.webmoment.app |
| 3 | Authorization: Bearer tok_abc123… |
| 4 | Accept: application/json |
| 5 | |
Caching and rate limits
Tokens are SHA-256 hashed before lookup, cached in Redis for 24 hours, and rate-limited per workspace plan. The current limits are listed in your workspace settings and the response headers:
X-RateLimit-Limit— total quota window.X-RateLimit-Remaining— quota remaining in the window.X-RateLimit-Reset— Unix timestamp when the window resets.Retry-After— seconds until the next request will be accepted (only set on 429 responses).
