Skip to main content

Browser origins

A key works from any server, and from no browser origin at all until you say otherwise.

That default is not caution for its own sake. A key is a bearer credential: whoever holds it spends your quota. If the API accepted requests from any origin, a single page one of your users visits could read your data with your key and you would see it only on the invoice.

The allowlist belongs to the key​

Each key carries its own list of origins. Not the account, the key.

That distinction is what makes the model useful rather than bureaucratic:

  • A key allowed on your test site does not work from your production site. One leaked there is useless here.
  • Revoking a key revokes its origins with it. There is no separate list left behind to clean up.
  • A key with an empty list is a server-side key. That is the default, and it is the right default: most integrations never call from a browser.

Origins are matched exactly​

An origin is scheme, host and port. Nothing else, and no wildcards.

AllowedRequest fromResult
https://app.example.comhttps://app.example.compasses
https://app.example.comhttps://www.app.example.comblocked — different host
https://app.example.comhttp://app.example.comblocked — different scheme
https://app.example.comhttps://app.example.com:8443blocked — different port

The exactness is deliberate. A wildcard would let a subdomain you do not control — one parked, expired, or taken over — spend your key.

What a blocked call looks like​

CORS is enforced by the browser, not by us, so a blocked request fails in a way that hides the cause. The request is either never sent or its response is thrown away before your code sees it, and what you get in the console is a generic network error with no status.

This is worth knowing because it is the one failure that looks like the API being down when it is not. Before you debug anything else, check three things in order:

  1. The origin you are calling from — not the URL you are calling, the page's own origin.
  2. Whether that exact origin, including scheme and port, is on that key's list.
  3. Whether the key you are sending is the key you think you are sending. GET /v1/me returns its prefix, which is the fastest way to tell.

Changing the list​

The origins on a key are yours to change, over the API, with that same key. No dashboard, no ticket, no waiting on us.

Read the current list:

curl -s https://api.tokenflow.tech/v1/me/origins \
-H "x-api-key: tf_live_…"
{ "origins": ["https://app.example.com"] }

Replace it. The list you send is the list you get — including the entries you are keeping:

curl -s -X PUT https://api.tokenflow.tech/v1/me/origins \
-H "x-api-key: tf_live_…" \
-H "content-type: application/json" \
-d '{"origins": ["https://app.example.com", "https://staging.example.com"]}'

Sending {"origins": []} closes the key to browsers again. That is a valid instruction, not a mistake, and it takes effect immediately.

What comes back when an entry is wrong​

The whole list is rejected — nothing is stored — and the response names the entry and the reason, so you fix one line instead of hunting through twelve:

{
"error": {
"code": "VALIDATION_FAILED",
"message": "request rejected",
"details": {
"field": "origins",
"index": 1,
"reason": "an origin is scheme, host and port only — drop any path, query or fragment"
}
}
}

Origins are normalised on the way in: scheme and host are lowercased, and a trailing slash is dropped, because a browser sends them that way. Nothing else is adjusted — https://example.com/app is refused rather than trimmed, since quietly turning a URL into an origin would authorise more than you asked for.

What a key can and cannot change​

A key changes its own list and nothing else. It cannot touch another key's origins, grant itself more permission, or extend its own expiry — the database privilege behind this endpoint covers exactly one column.