Authentication

Every request to Rhombus carries a credential. Which credentials a request can use, and where they go, depends on where the request goes: the REST API, the media and video hosts, the event WebSocket, or a camera on your local network. This page maps each credential to each destination and explains the authentication errors; the pages after it cover each credential in detail.

Choose a credential

Where each credential works

Cameras on your local network accept federated tokens only. That's deliberate: on the local network, every request carries a short-lived token that you can limit to the one camera it needs, never a long-lived key. See Streaming over LAN.

Hosts per destination (US & EU Regions lists the EU variants):

Request headers

A request names its scheme in x-auth-scheme and carries the credential in the header that scheme reads:

curl -X POST "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: $RHOMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Rules that apply everywhere:

• Header names and the scheme value are exact. x-auth-scheme: api-token works; Api-Token does not.
• Authorization: Bearer carries an OAuth access token only, on the REST API, the media hosts and the event WebSocket. A Bearer header with no x-auth-scheme is read as an OAuth access token. API keys never go in Authorization.
• Only federated tokens go in a URL. x-auth-scheme and x-auth-ft may be query parameters; API keys, OAuth access tokens and x-auth-org are read from headers only.
• Credentials are region-bound. A key or token from a US organization doesn't work on EU hosts, and the reverse. The error doesn't mention the region. See US & EU Regions.
• Lifetimes: an API key works until you delete it or until its expiry (expiresAtMs), if it has one. OAuth access tokens last one hour. Federated tokens last the durationSec you ask for when you mint them: one hour by default, at most 24 hours.
• Revocation takes effect within 60 seconds on every host. Deleting a key, changing its role or revoking an OAuth grant ends its access, and open WebSocket connections that used it are closed.
• Send Content-Type: application/json on every POST to the REST API, even with an empty body ({}).

Partner credentials

Partner keys, partner certificate keys and partner OAuth tokens use the same schemes as the organization credentials. To act in a client organization, send that organization's UUID in x-auth-org:

• x-auth-org is a header only; it's never read from a query parameter. It means the same for partner keys, certificates and OAuth tokens, and an empty value counts as absent.
• Outside the /api/partner/ endpoints, always send x-auth-org. A partner request without it still works, but the response carries Deprecation: true and Sunset: Tue, 05 Jan 2027 00:00:00 GMT, and after that date the request fails. The event WebSocket refuses a partner handshake without x-auth-org with 403 PERMISSION_REQUIRED.
• A malformed value returns 400 INVALID_AUTH_ORG; a client organization your partner account doesn't manage returns 403 PARTNER_CLIENT_ACCESS_DENIED.

See Partner API for listing clients and calling into them.

Reading authentication errors

Every error response from the REST API, the media hosts and the WebSocket handshakes has the same JSON body, and carries the request ID in the x-rhombus-txid header too:

{
  "msg": "Unauthorized",
  "error": true,
  "errorCode": "CREDENTIAL_EXPIRED",
  "errorMsg": "The supplied credential has expired.",
  "status": 401,
  "timestamp": 1792371600000,
  "txid": "yJ2kQw8LTaO1xX4hVd7mPA"
}

Branch on the status and errorCode, show or log errorMsg, and quote txid when you contact support. The status says which part of the request to fix:

• 401: Rhombus couldn't establish who is calling. The credential is missing, malformed, unknown, expired or revoked. Fix or replace the credential.
• 403: the credential is valid but isn't allowed to do this. Change the role, the OAuth scopes, the organization or the token's limits; a new credential of the same kind won't help.

Some operations report a refused action with HTTP 200 and "error": true in the body, so check the body as well as the status. The Errors page has the full catalog of codes and the retry rules.

Media hosts and the event WebSocket have their own failure cases; see Media and streams and WebSocket authentication.

Next steps