Authentication

The ControlCom Connect API supports two authentication methods: API key credentials passed as HTTP Basic, and a signed-in user's JSON Web Token passed as a Bearer token.

API Keys

API keys are created in ControlCom Connect under Settings → API keys. When you create a key you assign it a role, and the key inherits that role's permissions.

The creation screen shows the key's two credentials: the key ID and the secret. Copy the secret immediately; it is shown once and cannot be retrieved again. Keep it confidential and never expose it in client-side code.

API keys work on organization-scoped endpoints, which is every endpoint in this reference. Requests to paths without an organization id return 401 when authenticated with a key.

Basic Authentication

Combine the key ID and secret as id:secret, Base64-encode the result, and pass it in the Authorization header prefixed with Basic.

# macOS / Linux
echo -n "myApiKeyId:myApiKeySecret" | base64
# Outputs bXlBcGlLZXlJZDpteUFwaUtleVNlY3JldA==

Authorization: Basic bXlBcGlLZXlJZDpteUFwaUtleVNlY3JldA==

Most HTTP libraries handle the encoding for you when you supply the key ID as the username and the secret as the password.

Permissions

Endpoints that create, update or delete data require a permission, named on each endpoint page (for example CreateDevice). The request succeeds only when the API key's role, or the user's role for Bearer requests, allows every required permission. Otherwise the API returns 403 with the missing permissions listed:

{
  "missingPermissions": ["CreateDevice"],
  "message": "Request failed to complete. Missing required permissions"
}

A key that has no role assigned cannot perform permission-gated operations, so assign the role when creating the key.

Bearer Tokens

Authenticated user sessions can call the API with a JSON Web Token passed as a Bearer credential.

Authorization: Bearer <your-jwt>

A small number of operations act on behalf of a specific user and therefore require a user token rather than an API key. This reference marks them as user-token only; creating and modifying Dashboards is the main example.

For transport security and credential-rotation guidance, see the Security reference.