Authentication
Every ErreOS API request carries a token. The token identifies the workspace it belongs to. There is no account id, workspace id or tenant parameter anywhere in the API, and you never need to look one up.
Getting a token
Section titled “Getting a token”Tokens are issued inside ErreOS, under Settings, then API, by a workspace owner or admin. If you are building a site for a client, ask them to mint one and send it to you; you cannot create one yourself.
The two classes
Section titled “The two classes”| Publishable | Secret | |
|---|---|---|
| Prefix | erre_pk_ |
erre_sk_ |
| Safe in browser code? | Yes | No, server only |
| Can it read data? | Never | Yes, if granted |
| Restricted by site? | Yes, by an origin allowlist | No |
| Can it be shown again? | Yes | No, copied once at creation |
A publishable token is meant to be visible. It ships inside the JavaScript of a public web page, so treat it as public information. It is protected by being write-only and by only working from the sites its owner listed, not by being kept secret.
A secret token must never reach a browser. It goes in server-side code, environment variables, or a backend service. Anyone holding it can act as the workspace.
Pick publishable for a contact form on a website. Pick secret for a server, a build, or a serverless function: anything that reads content, and anything that posts on the site’s behalf.
Sending it
Section titled “Sending it”Authorization: Bearer erre_pk_your_token_hereRequests with a body must also send Content-Type: application/json.
Permissions
Section titled “Permissions”A token carries a fixed set of scopes, chosen when it was created:
| Scope | Grants |
|---|---|
contacts:write |
POST /api/v1/contacts |
companies:write |
POST /api/v1/companies |
files:write |
files sent with a contact (see Uploads) |
events:write |
POST /api/v1/events (see Events) |
content:read |
the four /api/v1/content/... routes (see Content) |
content:preview |
plus unpublished drafts, via ?preview=1 |
Scopes cannot be changed after a token is created. If you need a different set, the workspace admin rolls the token (which issues a replacement and gives the old one a grace period) or issues a new one.
A publishable token may only hold write scopes. If you need to read data, you need a secret token.
files:write is only granted together with contacts:write, because the files
arrive with the contact a form creates.
Origin allowlisting
Section titled “Origin allowlisting”A publishable token only works from the sites listed on it. The allowlist accepts three forms:
| Entry | Matches |
|---|---|
https://example.com |
exactly that origin (a port may be included) |
*.example.com |
any subdomain, at any depth |
http://localhost:* |
localhost on any port, for development |
Three rules worth knowing before you debug a 403:
- A wildcard never matches the apex.
*.example.comdoes not matchhttps://example.com. List the apex separately if you need both. - An empty allowlist rejects everything. A new token with no origins listed will refuse every request until origins are added.
httpsis required except forlocalhost.
Requests with no Origin header at all are rejected for publishable tokens.
Browsers always send one; a server-side caller does not, which is why a
server-side integration needs a secret token instead.
Status codes
Section titled “Status codes”| Status | Code | What to do |
|---|---|---|
201 |
Created. The response carries the new record’s id. |
|
200 |
Already existed, because you sent a repeated externalId. Carries deduplicated: true. |
|
304 |
Read endpoints only. Your If-None-Match still matches; there is no body. |
|
400 |
invalid_json |
The body was not valid JSON. |
400 |
invalid_content_type |
Send Content-Type: application/json. |
400 |
unknown_field |
You sent a field this endpoint does not accept. See the note on metadata in Contacts. |
400 |
name_required |
name is the one required field. |
400 |
field_too_long |
A field exceeded its cap. The message names the field. |
400 |
invalid_field |
A field was the wrong type, usually a number or object where a string was expected. |
400 |
body_too_large |
The request body exceeded 32 KB. |
401 |
unauthorized |
The token is missing, malformed, revoked or expired. Check you copied all of it. |
403 |
forbidden_scope |
The token is valid but lacks the scope this endpoint needs. Check its permissions in Settings, then API. |
403 |
forbidden_origin |
The site you are calling from is not on the token’s allowlist. Add it. |
404 |
unknown_collection |
Read endpoints only. No collection with that key in this workspace. Check ?collection= for a typo. |
429 |
rate_limited |
Too many requests. Back off and retry. See below. |
500 |
internal_error |
Something failed on our side. Retry. |
Every error response has the same shape:
{ "error": "forbidden_origin" }Some also carry a message explaining the specific failure:
{ "error": "unknown_field", "message": "\"service\" is not a field on this endpoint" }Note the asymmetry: success bodies have "ok": true, error bodies have no
ok field at all. Do not test body.ok === false. ok is undefined on
every error. Use the HTTP status to decide success or failure (res.ok in
fetch), then read error for the reason.
Branch on error, not on message. The message is written for a developer
reading a console and may change; the code will not.
A 403 forbidden_origin deliberately carries no CORS headers. In a browser
this surfaces as a network/CORS failure rather than a readable 403. That is
what makes the allowlist meaningful. If your fetch fails with a CORS error and
you have not added your site to the allowlist yet, that is why.
Rate limits
Section titled “Rate limits”| Limit | Applies to |
|---|---|
| 10 requests/minute per token | every authenticated write, including ones that then fail validation |
| 120 reads/minute per token (burst of 240) | the /api/v1/content/... routes |
| 120 calls/minute per token (burst of 240) | the /api/v1/uploads routes |
| 30 failed authentications/hour per IP (burst of 10) | wrong, missing or revoked tokens |
The request limits are separate buckets on purpose: a nightly site build, or one visitor sending twenty photos, must not be able to throttle the same workspace’s contact form.
A 429 carries a Retry-After header in seconds. Read it and wait. Do not
retry immediately in a loop.
On the write endpoints, bursts are limited and daily volume is not. There is no daily cap that rejects submissions. A busy day never causes a lead to be turned away.
File uploads are the one exception: a token may reserve 2 GB of files a day, and
past that a file is refused with 429 while contacts are still saved.
Uploads has the reason and the other upload limits.
Reads are counted per day per workspace, but that number rejects nothing today. It exists so we can answer “how much is this site reading” without a log grep.
Rotation and revocation
Section titled “Rotation and revocation”A workspace admin can roll a token: this issues a replacement and puts the old one on a grace period of immediately, 24 hours, or 7 days. Both tokens work until the grace expires, so you can deploy the new one without downtime.
Revocation is immediate and permanent. A revoked token cannot be restored. A replacement has to be issued and deployed.
If your integration suddenly starts returning 401, the token was almost
certainly revoked or its grace period ran out. Ask the workspace admin.
Hostnames
Section titled “Hostnames”The API is served from:
https://api.erreos.comThe copy-paste snippet in Settings, then API, shows the host to use. If this page and the snippet ever disagree, believe the snippet.
Paths are versioned (/api/v1/...), so a future version will not change these routes.