Reference
Authentication API
REST endpoints for user login and server-to-server token issuance.
All Breeze Buddy endpoints require a Bearer token in Authorization: Bearer <token>. For a conceptual overview of when to use which token, see Authentication.
POST /login
Exchange email and password for a short-lived JWT access token.
POST
/login Request
{
"email": "user@example.com",
"password": "your-password"
}| Field | Type | Required | Description |
|---|---|---|---|
email | string | yes | User email. |
password | string | yes | User password. |
Response — 200 OK
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"user": {
"id": "usr_abc123",
"email": "user@example.com",
"role": "admin",
"reseller_id": "res_001"
}
}| Field | Type | Description |
|---|---|---|
access_token | string | JWT. Include as Authorization: Bearer <token> on subsequent requests. |
token_type | string | Always bearer. |
user.id | string | Stable user identifier. |
user.email | string | Email the user authenticated with. |
user.role | string | One of admin, reseller, merchant, user. See RBAC. |
user.reseller_id | string | Reseller scope the user belongs to. |
Errors
| Status | Meaning | Common cause |
|---|---|---|
401 | Unauthorized | Missing or expired token on a protected route (not thrown by /login itself). |
403 | Forbidden | Token role lacks permission for the requested resource. |
422 | Unprocessable Entity | Email or password missing, malformed, or incorrect. |
Token expiry
Access tokens are short-lived. Call /login again to issue a new one — there is no refresh endpoint.
POST /s2s-token
Issue a long-lived server-to-server token. Use these for backend integrations that push leads or manage templates on behalf of a reseller or merchant.
POST
/s2s-token Request
{
"name": "my-backend-integration",
"role": "merchant",
"reseller_id": "res_001",
"merchant_id": "mer_abc"
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Human-readable identifier for the token (shown in audit logs). |
role | string | yes | reseller, merchant, or user. Determines permission scope. |
reseller_id | string | yes | Reseller under which the token operates. |
merchant_id | string | when role is merchant or user | Merchant the token is scoped to. |
Response — 200 OK
{
"token": "s2s_eyJhbGciOiJIUzI1NiIs...",
"name": "my-backend-integration",
"role": "merchant",
"reseller_id": "res_001",
"merchant_id": "mer_abc",
"created_at": "2026-04-14T10:00:00Z"
}Keep S2S tokens secure
S2S tokens grant persistent access. Store them in environment variables or a secrets manager — never commit them to source control.
Errors
| Status | Meaning | Common cause |
|---|---|---|
403 | Forbidden | Caller role cannot issue a token at the requested scope. |
422 | Unprocessable Entity | Missing merchant_id when role requires it, or unknown reseller_id. |
Was this helpful?