All protected endpoints require an API key in the request header. Public endpoints need no authentication.
API Key Header
Include x-api-key on every protected request.
x-api-key: YOUR_API_KEY
Important
Keep your key secret Never expose your API key in client-side code or public repositories. Store it in environment variables.
Public Endpoints
These endpoints do not require x-api-key.
GET /api/v1/health
GET /api/v1/status
Protected Endpoints
All of the following require a valid x-api-key.
POST /api/v1/initialize
POST /api/v1/setup
POST /api/v1/sync
GET /api/v1/codes
GET /api/v1/customers/:pin
GET /api/v1/notices
GET /api/v1/branches
POST /api/v1/items/service
POST /api/v1/items/goods
POST /api/v1/items
GET /api/v1/items
POST /api/v1/sales
POST /api/v1/sales/credit-note
GET /api/v1/purchases
POST /api/v1/purchases
POST /api/v1/stock/io
PUT /api/v1/stock/master
GET /api/v1/stock/movements
Sandbox vs Production
API keys are per app. Each named app is either Sandbox or Production and never switches.
| Prefix | Environment | When issued |
|---|---|---|
ush_test_… | Sandbox | Creating a Sandbox app (auto-provisioned) or minting a key in that app |
ush_live_… | Production | Minting a key on an active Production app |
The key selects the workspace app (and thus KRA device + environment). Dashboard JWT calls must also send X-Ushuru-App-Id when working inside an app.
x-api-key: ush_test_…
or
Authorization: Bearer <jwt>
X-Ushuru-App-Id: <app-uuid>
Production
For live transactions. Requires a production key from a Production app in your Ushuru dashboard.