Authentication
How Breeze Buddy authenticates API requests — JWT access tokens for users, server-to-server tokens for backends.
Every Breeze Buddy API call carries a Bearer token. The platform recognises two distinct token types — short-lived JWT access tokens for human users, and long-lived server-to-server (S2S) tokens for backend integrations. Picking the right one depends on who is making the call and how long the credential needs to live.
Two token types
| Access token (JWT) | S2S token | |
|---|---|---|
| Issued by | POST /login with email + password | POST /s2s-token with role and scope |
| Lifetime | Short — minutes to hours | Long — until manually revoked |
| Caller identity | A specific user account | A named integration |
| Use case | Dashboard session, CLI for a person | Backend services pushing leads, CRON jobs, CI |
| Rotation | Re-issued on every login | Rotate manually on a schedule |
| Where it lives | Browser memory or keychain | Secrets manager, env var |
Both tokens are sent the same way:
Authorization: Bearer <token>The server treats them identically at the transport layer. The difference shows up in how they’re minted and the permissions they encode.
Scope and permissions
Every token carries a role (admin, reseller, merchant, user) and the IDs it is scoped to. The role determines what the token can read and write; the IDs determine whose data. See RBAC for the permission model.
A merchant-scoped S2S token, for example, can push leads and read analytics for that merchant — and nothing else. An admin access token can do everything, but only until it expires.
When to use which
- Building a dashboard or CLI that users sign into? Use login + access token. The short lifetime limits blast radius if the token leaks.
- Running a backend cron or an integration in your own infrastructure? Use an S2S token. Scope it to the narrowest role and reseller/merchant combination that works.
- Testing in a terminal? Either works. S2S is less friction because you don’t re-authenticate every hour.
Security model
- Tokens are signed JWTs. Tampering invalidates them.
- There is no token-refresh endpoint — re-issue by calling
/loginagain. - S2S tokens persist until revoked. Rotate them on a schedule and watch your audit log.
- Never commit tokens to source control. Use environment variables or a secrets manager.
What to read next
- Authentication API — endpoint reference for
/loginand/s2s-token. - RBAC — the role hierarchy and what each role can do.
- Architecture — how auth fits into the request lifecycle.