API Authentication

Overview

The Gateway REST API uses JWT (JSON Web Tokens). Integration administration uses a separate login token, while third-party systems use a dedicated vendor API key. Follow the section for the API surface you are calling.

Tokens expire after 1 hour by default. Use the refresh token to obtain a new access token without re-entering credentials.

Base URL

http://<gateway-ip>:5000/api

Replace <gateway-ip> with your C-Bridge device's IP address or hostname (e.g., 192.168.1.100 or cbridge.local).

Step 1: Generate a Token

POST /api/auth/generate-token

Generate an access token using your C-Bridge account credentials.

Request Body

{
  "email": "admin@cbridge.local",
  "password": "your-password"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "def50200a1b2c3...",
  "expiresIn": 3600
}

Step 2: Use the Token in Requests

Include the token as a Bearer token in the Authorization header of every API request:

Authorization: Bearer <token>
Content-Type: application/json

Example Request

curl -X GET http://cbridge.local:5000/api/devices \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Step 3: Refresh the Token

When the access token expires, use the refresh token to get a new one without re-authenticating.

POST /api/auth/refresh

Request Body

{
  "refreshToken": "def50200a1b2c3..."
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

Expose Integration API Authentication

The Expose Integration API (used to register and manage third-party integrations, e.g. Crestron, other lighting platforms, BMS systems) has its own login endpoint, separate from the Gateway token above.

POST /api/auth/login

Request Body

{
    "email": "you@example.com",
    "password": "your-password"
}

Response

{
  "success": true,
  "user": { "email": "you@example.com", "role": "admin" },
  "tokens": { "accessToken": "eyJhbGciOi..." }
}

Use tokens.accessToken as a Bearer token on every /api/integrations/* call:

Authorization: Bearer <accessToken>

This token is required for creating, listing, updating, testing, syncing, and deleting integrations, and for reading their devices, allow-lists, health, events, and audit logs.

Vendor Credential Authentication (Third-Party Systems)

When a third-party system (the one being integrated, e.g. Crestron) calls C-Bridge's /api/vendor/* endpoints directly, it does not use the admin login above. Instead it uses the dedicated vendor credential issued when its integration was created (vendorCredentialId and apiKey from the POST /api/integrations response).

The apiKey is a single self-contained token in the form <vendorCredentialId>.<secret> — the credential ID is already embedded in it. Send it as one header on every /api/vendor/* request; no separate X-Credential-ID header is required:

Authorization: Bearer <apiKey>
Content-Type: application/json

A credential is scoped to only the operations (monitor, read, control) and devices/scenes granted to its integration — see Third-Party Lighting Integration for the full contract, the endpoint list, and how device exposure is controlled.

Verify a vendor credential

GET /api/vendor/me — returns the credential's identity and exactly which operations and devices it may access. Use it as a one-call health check when setting up an integration:

curl -s http://<gateway-ip>:5000/api/vendor/me \
  -H "Authorization: Bearer <apiKey>"

{
  "success": true,
  "data": {
    "credentialId": "72e128ae-0f67-4b5e-aa07-0237cd8ed9f2",
    "name": "Crestron Test (Vendor API)",
    "authType": "bearer",
    "allowedOperations": ["monitor", "read", "control"],
    "allowedDeviceIds": [],
    "allowedSceneIds": [],
    "restricted": false
  }
}

Empty allowedDeviceIds/allowedSceneIds mean the credential can see every exposed device and scene; populate the allow-list to restrict it (see Third-Party Lighting Integration).

Error Responses

Error Response Format

{
  "error": "Unauthorized",
  "message": "Token expired",
  "statusCode": 401
}

Vendor Credential Errors

These use a code field for programmatic matching, in addition to the HTTP status:

Security Best Practices

• Store tokens securely — do not expose them in client-side code or logs
• Use HTTPS where possible (configure TLS on your network or reverse proxy)
• Rotate credentials if a token is believed to be compromised
• Use dedicated API credentials rather than personal admin accounts for integrations
• Set short token lifetimes for untrusted environments

Related Articles

• API Reference — Full list of available endpoints

API Reference

Third-Party Lighting Integration

• WebSocket → Real-time event subscription
• System Overview — Platform architecture and authentication model