Signing in
Who's making this request — a customer, a member of staff, or your software? Pick by that, not by what's convenient.
Sarah's setup has four different things talking to the API, and they don't sign in the same way:
- A customer on the booking page, seeing their own visits
- A cleaner checking Thursday's rounds on their phone
- Sarah's Sunday email job, running on a server at 6am
- Sarah herself, opening a new site in the dashboard
The right credential follows from who's actually asking.
Pick one
| Who's asking | Use | Guide |
|---|---|---|
| Your server, on its own behalf | Secret key (sk_…) | Server apps |
| A person in a browser | Session cookies | Browser apps |
| Anyone, for public read-only data | Publishable key (pk_…) | Keys |
| A person in a mobile app | Personal token | Server apps |
| Your own staff, running the business | Staff token | Staff and roles |
Can't decide? If it's software acting by itself, you want a secret key. If a person is waiting for the response, you probably want their session or token.
The one rule that matters
A secret key never leaves your server. Not in a JavaScript bundle, not in a mobile app binary, not in a repository. If a browser can read it, it's compromised — and it carries everything you granted it.
How the API tells them apart
They all arrive in the same place, and the prefix decides how it's read:
Authorization: Bearer sk_live_... → a key, everything you granted it
Authorization: Bearer pk_live_... → a key, capped to read-only
Authorization: Bearer 12|abc... → a person's token
Cookie: <session> → a browser session, sent automaticallyYou never set the session cookie yourself — the browser stores it at sign-in and attaches it to later requests, as long as you send them with credentials.
Keys also work as HTTP Basic, with the key as the username and no password. That exists
because it's what curl -u and most HTTP libraries make easy:
# These two are the same request.
curl https://api.hyphabase.com/api/modules/clients -u sk_live_xxx:
curl https://api.hyphabase.com/api/modules/clients -H "Authorization: Bearer sk_live_xxx"Getting in is not the same as being allowed
A valid credential gets you through the door. Two more checks run on every request about a site:
- Can this credential reach that site?
- Is it allowed to do this thing?
Both come back 403, and both are common while wiring up.
Who can do what covers them, including
how to tell which one you've hit.