---
title: API Authentication
description: Authenticate to the ControlCom Connect REST API using API key credentials (HTTP Basic) or a user JSON Web Token (Bearer).
source: https://documentation.controlcomtech.com/api-reference/authentication
---

# 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.

> **Workflow Stage: Integrate**

## 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`.

```sh
# 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:

```json
{
  "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](https://documentation.controlcomtech.com/api-reference/dashboards) is the main example.

For transport security and credential-rotation guidance, see the [Security reference](https://documentation.controlcomtech.com/references/security).