Authentication
API keys, test and live environments, scopes and request IDs.
API keys
Every request is authenticated with an API key in the Authorization header. Keys are created per project in the dashboard and look like this:
| Prefix | Environment | Format |
|---|---|---|
fd_test_ | Test (sandbox data) | fd_test_ + 40 base62 characters |
fd_live_ | Live (authorized upstream data) | fd_live_ + 40 base62 characters |
Authorization: Bearer fd_live_xxxxxxxxx- The raw secret is shown once, at creation. FomoData stores only a display prefix and a keyed hash, never the key itself.
- Never put keys in URLs. A request with
?api_key=or?key=in the query string is rejected with400 INVALID_REQUEST, even if the header is also present. - Keep live keys on your server. Browser code should only ever hold a test key, and only for experiments like the playground.
- Revocation takes effect immediately. Keys can optionally expire.
Test and live
A key's environment decides which data it can see. Test keys only see sandbox rows (livemode: false, source: "sandbox"), shared fixtures plus the test theses your project creates. Live keys only see live rows (livemode: true, source: "fomo", or "fomodata" for events derived from them).
Live access by approval during the private beta
Anyone can create test keys. Live keys work only for projects a FomoData admin has approved; until then live requests return 403 LIVE_ACCESS_NOT_APPROVED. Request access from your project's settings.
Sandbox fixtures
Test keys share a fixed, clearly fake data set. Every object is livemode: false, source: "sandbox", and display names end in (sandbox). None of it is real Fomo activity.
| Fixture | Values |
|---|---|
| Profiles | @sbx_milo, @sbx_juno, @sbx_pixel, @sbx_rio, @sbx_nova, @sbx_remi, @sbx_kai, @sbx_wren |
Tokens (chain sandbox) | $RUN, $SEEK, $RACE, $TAG, $ART, $CRAFT |
| Theses | About 150 seeded theses spread over 7 days, queryable with every thesis filter and verifiable with POST /v1/verify/thesis. |
| Live-like feed | A labelled ticker adds one fixture thesis about every 45 seconds on this deployment, with its thesis.created event and the derived token.activity / token.thesis_velocity events. They reach every test-mode stream and webhook subscribed to those types. |
chain: "sandbox" is not a real chain. Need a specific scenario? Create project-only test theses with POST /v1/test/theses (test keys only); any new @handle or $SYMBOL becomes a test profile or token visible to your project alone.
Scopes
Keys are least-privilege. Each endpoint requires one scope, listed on its reference page. A request without it fails with 403 INSUFFICIENT_SCOPE.
| Scope | Grants | Default |
|---|---|---|
profiles:read | Resolve Fomo profiles by handle or id. | default |
theses:read | List, read and verify Trade Theses. | default |
tokens:read | Token metadata, activity and thesis velocity. | default |
search:read | Search theses, profiles and tokens. | default |
wallets:read | Public wallet associations (only when the Wallets API is enabled). Coming soon | — |
events:read | List and fetch historical events. | default |
streams:read | Consume realtime events over WebSocket / SSE. | default |
webhooks:write | Create and manage webhook endpoints. | — |
webhooks:write is opt-in because it can create outbound deliveries. wallets:read can only be granted once the Wallets API is enabled for public, authorized associations.
Inspect the current key
GET /v1/me works with any valid key and returns its project, organization, plan, environment and scopes. It's the quickest way to check a key.
/v1/mecurl 'https://fomodata.dev/v1/me' \
-H "Authorization: Bearer $FOMODATA_API_KEY"Request IDs
Every response, including errors, carries X-FomoData-Request-Id (req_…). Error bodies repeat it as error.request_id. Log it alongside your own request logs; it's how support finds your request in ours.
Authentication errors
| Status | Code | When |
|---|---|---|
| 401 | MISSING_API_KEY | No Authorization header, or not a Bearer token. |
| 401 | INVALID_API_KEY | The key doesn't exist or is malformed. |
| 401 | API_KEY_REVOKED | The key was revoked. |
| 401 | API_KEY_EXPIRED | The key passed its expiry. |
| 403 | INSUFFICIENT_SCOPE | The key lacks the endpoint's scope. |
| 403 | LIVE_ACCESS_NOT_APPROVED | A live key on a project without live approval. |
| 403 | PROJECT_ARCHIVED | The key's project is archived. |
Failed attempts
Repeated authentication failures from one IP are rate limited (20 per minute) and flagged for abuse review. Rotate any key you suspect has leaked: create a new one, deploy it, then revoke the old one.