Authentication
samo_live_ keys, scopes, IP allowlists and what happens when the plan changes.
Every request is authenticated with a company key in the Authorization header:
Authorization: Bearer samo_live_XXXXXXXXXXXXXXXXXXXXXXXX
A key represents exactly one company. Everything you create with it belongs to that company, and you can only see that company's listings — even if the user who issued the key also has access to other companies.
Issuing and revoking
Keys are created by the company owner in the dashboard: Settings → API.
- The full key is shown once, right after creation. The list afterwards only shows a prefix so you can tell keys apart.
- You can hold several keys — one per integration is convenient, because you can revoke them independently.
- A revoked key stops working immediately; subsequent requests get
401 unauthorized.
Store the key the way you store a database password: in environment variables or a secret manager, never in a repository, a browser or a mobile app. A key can create and delete the company's listings.
Scopes
Scopes are chosen when the key is created. This is least privilege in practice: an integration that only reads the exchange has no business deleting your listings.
| Scope | What it unlocks |
|---|---|
reference:read | Dictionaries, locality search, company profiles and reviews |
proposals:read | Exchange search, listing detail, list of your own listings |
proposals:write | Create, update, bump, archive, restore and delete your own listings |
employees:read | List company staff and how many listings each of them is contact for |
employees:write | Activate/deactivate an employee and change their role |
The employees:* scopes are not granted by default — tick them explicitly when creating a key.
Keys issued earlier do not carry them: to manage staff through the API, create a new key.
A request missing the required scope fails with 403 forbidden; the message field says which.
IP restrictions
A key can carry an allowlist of IP addresses. A request from any other address is then rejected
with 403 forbidden, even if the key is valid. This is useful when the integration runs from a
known static server.
An empty list means "any address".
What happens on a plan change
API access is tied to the company's plan:
- moving to a plan without API access stops keys from authenticating and switches off the company's active webhooks;
- returning to PREMIUM restores both — nothing has to be reissued.
The change takes effect almost immediately: the permission cache is dropped by an event, not by a timer.
Common problems
| Symptom | Cause |
|---|---|
401 unauthorized on the very first call | missing header, missing Bearer, truncated key |
401 after working fine for a while | key revoked, or the company's plan no longer includes API access |
403 forbidden on one endpoint | the key lacks the required scope |
403 forbidden everywhere | the request comes from an IP outside the allowlist |
404 not_found on someone else's listing | it belongs to another company — the API deliberately does not distinguish "missing" from "not yours" |