Skip to content

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.

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.

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.

Authorization: Bearer erre_pk_your_token_here

Requests with a body must also send Content-Type: application/json.

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.

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.com does not match https://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.
  • https is required except for localhost.

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 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.

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.

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.

The API is served from:

https://api.erreos.com

The 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.