Authentication

C21 Live Control authenticates two classes of caller:

• Human operators signing in to the web UI use a session cookie. The session is established by the standard sign-in form against the user catalogue.
• Non-interactive callers — the REST API and the MCP server — use an API token, a bearer credential issued to an existing user.

Both paths share the same authorisation model: every call is associated with a user, and the user's role (System Administrator or Operator) gates what the call can do.

API tokens

Create

POST /c21apiv2/security/tokens issues a new token. The request body accepts:

The response carries the full token exactly once:

{
  "data": {
    "id": 12,
    "kid": "<key-id>",
    "token": "<the full bearer string>",
    "name": "mcp-server-dev",
    "created_at": "2026-05-18T10:00:00Z",
    "expires_at": "2026-08-16T10:00:00Z"
  }
}

The server stores only the token's hash. Store the returned token value in a secret manager — it is never returned again.

Creating a token requires the System Administrator role.

Use

Callers pass the token in the standard bearer header:

Authorization: Bearer <YOUR_API_TOKEN>

The token authenticates as the user it was issued to and inherits that user's role.

List

GET /c21apiv2/security/tokens returns the catalogue of tokens. Each row exposes id, kid, name, created_at, expires_at — the secret value is never echoed back.

Revoke

DELETE /c21apiv2/security/tokens/{kid} revokes a token by its kid. Subsequent calls with that token return 401 Unauthorized.

Rotate

There is no rotate operation. To rotate a token without downtime:

1. Create a new token (POST /c21apiv2/security/tokens).
2. Update the integration to use the new token.
3. Confirm the integration is operating against the new token.
4. Revoke the old token (DELETE /c21apiv2/security/tokens/{kid}).

Field length limits

The username, first_name and last_name fields are limited to 30 characters; email accepts up to 75. The API rejects oversized values up-front with a validation error (HTTP 400) and names the offending field in the envelope. The OpenAPI spec exposes the maxLength on each field definition.

Storage advice

Treat API tokens as secrets:

• Never commit a token to source control.
• Store tokens in the host's secret store (Kubernetes secrets, HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, GitHub Actions secrets).
• Rotate on a schedule. Recreate the token, switch over, verify, revoke the old one.
• One token per caller. Audit becomes ambiguous and revocation becomes destructive when tokens are shared between unrelated services.

FAQ