REST API Reference

Who this is for: Developers integrating with the TrustBridge backend programmatically.

What you'll learn: The REST API's authentication model and its main resource groups. The full request/response schemas are browsable interactively in Swagger.

The backend exposes a REST API under the /api prefix. The complete, interactive documentation is in Swagger at http://localhost:3000/docs, this article is a map of what's there, not a replacement for it.

Authentication model

All endpoints require a Bearer JWT except those marked Public. You obtain a token from POST /api/auth/login and pass it as Authorization: Bearer <token> on subsequent calls.

Resource groups

Authentication (/api/auth), POST /login, POST /forgot-password, POST /reset-password, POST /set-password (all Public); GET and PATCH /profile, GET /me, POST /change-password, POST /initialize (JWT).

Devices (/api/devices), POST / (register), POST /bulk-import, POST /bulk-authenticate, POST /lifecycle/bulk-auth, POST /:id/authenticate, GET / (list / search / paginate), GET /by-status, GET /status-counts, GET /:id, GET /:id/logs, GET /:id/connectivity, GET /export, PATCH /:id, DELETE /:id. Public SDK-facing helpers: GET /credentials-by-tid and GET /whitelist (the gateway's whitelist source).

Device Groups, Device Profiles, and Master Data, /api/device-groups, /api/device-profiles, and categories / sub-categories / tags under /api/master-data/{categories|sub-categories|tags}. Each exposes the standard set: POST /, GET /, GET /:id, PATCH /:id, DELETE /:id.

Identity & access, Users (/api/users), Roles (/api/roles), Permissions (/api/permissions), and Organizations (/api/organizations, including /:id/tenants) provide full CRUD plus role and permission assignment. Tenant integration (/api/tenant-api) proxies SandGrain / CyberRock credentials and IoT-user calls. Dashboard statistics (/api/dashboard/stats) and audit logging (/api/system-activity) complete the surface.

Service discovery, GET /api/discover returns the resolved backend base URL, which the frontend uses to configure its API client at runtime.

Two endpoints the SDK itself uses

GET /api/devices/whitelist: the Gateway syncs its device whitelist from here (it derives BE_URL = http://<laptop-ip>:3000/api).
GET /api/devices/credentials-by-tid: the Cloud SDK agent fetches per-device credentials on demand.

Error responses

Errors surface as sgr_sdk_status_t codes on the SDK side and as API/BE responses on the REST side (for example, an installation denial carries the reason fw_verification_failed and ErrorResult.FW_INSTALL_NOT_ALLOWED). Rate limiting on the SDK side is governed by the configured retry limits (MAX_RETRIES, GW_MAX_RETRIES).