API Overview

The Flavor Hub API is a RESTful API that allows programmatic access to license management, client operations, and more. It's built on FastAPI and follows standard REST conventions.

Base URL

https://admin.flavorteam.dev/api/v1

All endpoints are prefixed with /api/v1.

Authentication

The API supports two authentication methods:

JWT Bearer Token

Used for all portal endpoints. Obtained via the login endpoint.

# Login to get tokens
curl -X POST https://admin.flavorteam.dev/api/v1/portal/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "user": {
    "id": 1,
    "email": "you@example.com",
    "name": "Your Name",
    "type": "reseller"
  }
}

Use the access token in subsequent requests:

curl -H "Authorization: Bearer eyJ..." \
  https://admin.flavorteam.dev/api/v1/portal/licenses

Token lifecycle:

• Access tokens expire after 30 minutes
• Use the refresh endpoint to get a new access token:

curl -X POST https://admin.flavorteam.dev/api/v1/portal/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJ..."}'

API Key

Available to Reseller and Agency accounts for programmatic access. Passed via the X-API-Key header.

curl -H "X-API-Key: fh_live_abc123..." \
  https://admin.flavorteam.dev/api/v1/portal/licenses

API keys provide access to a subset of endpoints (licenses and clients). See API Keys for details on creating and managing keys.

Endpoints accessible via API Key:

Endpoint	Method	Description
/portal/licenses	GET	List licenses
/portal/licenses	POST	Create license
/portal/licenses/bulk	POST	Bulk create licenses
/portal/licenses/{id}/reactivate	POST	Reactivate license
/portal/clients	GET	List clients
/portal/clients	POST	Create client
/portal/clients/{id}	DELETE	Delete client
/portal/clients/{id}/licenses	GET	Get client licenses

All other endpoints require JWT Bearer authentication.

Rate Limiting

API endpoints are rate-limited to prevent abuse:

Endpoint Category	Limit
Login / Register	5/minute
Forgot Password / Resend Verification	3/minute
Token Refresh	10/minute
License Activate / Deactivate	10/minute
License Verify	30/minute
Update Check / Info	30/minute
Download	5/minute
Component List / Available / Check	30/minute
Component Download	100/minute

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Response Format

All responses are JSON. Successful responses return the data directly:

{
  "id": 42,
  "license_key": "FLVR-ABCD-EFGH-IJKL-MNOP",
  "tier": "starter",
  "status": "active"
}

Error responses include a detail field:

{
  "detail": "License not found"
}

Common HTTP status codes:

Code	Meaning
200	Success
201	Created
204	Deleted (no content)
400	Bad request (invalid input)
401	Unauthorized (missing/invalid auth)
403	Forbidden (insufficient permissions)
404	Not found
422	Validation error (invalid field values)
429	Rate limited

Pagination

List endpoints that support pagination accept these query parameters:

Parameter	Default	Description
page	1	Page number
per_page	25	Items per page

Paginated responses include:

{
  "items": [...],
  "total": 150,
  "page": 1,
  "per_page": 25
}

Content Type

All request bodies must be application/json unless otherwise specified (e.g., file uploads use multipart/form-data).