API Reference Overview

Base URL

https://services.cephable.com/

All requests must be made over HTTPS. The API uses JSON for both request and response bodies.

For the full, interactive API reference see the Swagger UI.

Authentication overview

Cephable uses OAuth 2.0 Authorization Code flow. Your application redirects users to the Cephable login page, receives an authorization code on redirect, and exchanges it for access and refresh tokens.

You will need:

• OAuth Client ID — obtained from the Cephable Portal
• OAuth Client Secret — obtained from the Cephable Portal
• Device Type ID — the ID of the device type you registered in the Cephable Portal

See Authentication for the full details.

Device API

The device API manages User Devices — virtual controllers that appear in a user's Cephable app after they authenticate.

Create a User Device

POST https://services.cephable.com/api/Device/userDevices/new/{deviceTypeId}?name={deviceName}
Authorization: Bearer {userAccessToken}

Response:

{
  "id": "...",
  "nameOverride": "Web-Sample",
  "isVerified": false,
  "isConnected": false,
  "isListening": false,
  "isAutoListen": false,
  "isOptimisticModel": false,
  "currentProfile": null
}

Create a Device Token

Once you have a user device, create a device token to authenticate the SignalR hub connection:

POST https://services.cephable.com/api/Device/userDevices/{userDeviceId}/tokens
Authorization: Bearer {userAccessToken}

Response:

{
  "id": "...",
  "userDeviceId": "...",
  "token": "...",
  "isDisabled": false
}

The token value is used as the X-Device-Token header (and bearer token) when connecting to the device hub.

Device Hub (SignalR)

After creating a device token, connect to the real-time hub to receive commands from the Cephable app. The hub uses ASP.NET Core SignalR.

Hub URL

https://services.cephable.com/device

Connecting

Pass the device token as both a bearer token and the X-Device-Token header:

// JavaScript (using @microsoft/signalr)
const connection = new signalR.HubConnectionBuilder()
  .withUrl("https://services.cephable.com/device", {
    accessTokenFactory: () => deviceToken,
    headers: { "X-Device-Token": deviceToken },
  })
  .withAutomaticReconnect()
  .build();

await connection.start();
// Identify device to hub
const device = await connection.invoke("VerifySelf");

Incoming events (hub → client)

Event	Description
DeviceCommand	User triggered an input command — carries the command string
DeviceProfileUpdate	User's active profile changed — carries updated UserDevice
DeviceSettingsUpdate	Device settings changed
DeviceType	Device type information
StartListening	Hub instructed device to start listening
StopListening	Hub instructed device to stop listening

DeviceCommand

connection.on("DeviceCommand", (command, macro) => {
  console.log("Command: " + command);
  console.log("Macro: " + JSON.stringify(macro));
});

DeviceProfileUpdate

connection.on("DeviceProfileUpdate", (device) => {
  const profile = device.currentProfile?.configuration;
  // update local state with new profile
});

Outgoing messages (client → hub)

Method	Description
VerifySelf	Identifies the connected device; returns the current UserDevice
GetLatestDevice	Requests the latest device state
DeviceStartedListening	Notifies the hub that the device is ready to receive commands
DeviceStoppedListening	Notifies the hub that the device has stopped listening

await connection.invoke("VerifySelf");
await connection.invoke("DeviceStartedListening");

UserDevice data model

{
  "id": "string",
  "nameOverride": "string",
  "isVerified": true,
  "isConnected": true,
  "isListening": true,
  "isAutoListen": false,
  "isOptimisticModel": false,
  "currentProfile": {
    "id": "string",
    "name": "string",
    "userId": "string",
    "profileType": "string",
    "configuration": {
      "profileType": "string",
      "commandKeyMappings": [],
      "macros": [],
      "hotkeys": [],
      "dictationCommands": [],
      "audioEvents": []
    }
  }
}

Macro event types

When a user triggers a command, the hub delivers both the command string and the associated macro. Macro events have the following types:

["KeyPress", "Pause", "Type", "MouseMove", "JoysticksMove", "PlayAudio",
 "KeyRelease", "StopOutputs", "KeyToggle", "DeviceTypeCustomAction"]

Example macro payload:

{
  "id": "2c13dc42-6e06-4e03-a780-798cb86cef1a",
  "name": "Move Forward",
  "commands": ["move forward", "go forward", "head_tilt_forward"],
  "events": [
    {
      "eventType": "KeyPress",
      "keys": ["w"],
      "holdTimeMilliseconds": 0,
      "isKeyLatch": false
    }
  ]
}

Next steps

• Authentication — OAuth flow details
• Swagger UI — Full interactive API reference
• Virtual Controller Integration — Use the hub in your app