CLI Tokens

CLI tokens are long-lived API tokens with granular scope-based permissions. They are designed for CI/CD pipelines, automation scripts, and the Controlinfra CLI.

Creating a Token

Via the Dashboard

1. Log in to the Controlinfra Dashboard
2. Go to Settings > API Tokens
3. Click Create Token
4. Enter a name (e.g., "GitHub Actions CI")
5. Select the scopes you need
6. Choose repository access (all or specific repos)
7. Copy the token — it's only shown once

Via the API

curl -X POST https://api.controlinfra.com/api/auth/cli-tokens \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Actions CI",
    "scopes": ["repos:read", "scans:read", "scans:trigger", "drifts:read"],
    "allRepositories": true
  }'

WARNING

The full token value (starting with ci_) is only returned once at creation time. Store it securely — you cannot retrieve it later.

Available Scopes

Scope	Allows
repos:read	List and view repository configurations
repos:write	Create, update, delete repository configurations
scans:read	List and view scan results and dashboard
scans:trigger	Trigger new scans and cancel running scans
drifts:read	List and view drift details, export CSV
drifts:write	Update drift status, generate fixes, create PRs
runners:read	List and view runner details
runners:manage	Create, update, delete runners

Repository Access

Tokens can be scoped to specific repositories:

• All repositories (allRepositories: true) — Access all current and future repos
• Specific repositories — Access only the listed repository config IDs

{
  "name": "Prod Only",
  "scopes": ["scans:read", "drifts:read"],
  "allRepositories": false,
  "repositories": ["repo-config-id-1", "repo-config-id-2"]
}

Using a CLI Token

CLI tokens work like JWT tokens — pass them in the Authorization header:

curl -H "Authorization: Bearer ci_abc123..." \
  https://api.controlinfra.com/api/scans/dashboard

Request Signing (Optional)

For enhanced security, CLI tokens support HMAC-SHA256 request signing. This prevents token theft via man-in-the-middle attacks and replay attacks.

Signing Headers

Header	Description
x-cli-signature	HMAC-SHA256 signature hex string
x-cli-timestamp	Unix timestamp in milliseconds
x-cli-nonce	Unique random string per request

Signature Algorithm

signature = HMAC-SHA256(
  key: token,
  data: "{timestamp}:{nonce}:{METHOD}:{path}:{bodyHash}"
)

Where bodyHash = SHA256(JSON.stringify(requestBody)).

Example (Node.js)

const crypto = require('crypto');

function signRequest(token, method, path, body) {
  const timestamp = Date.now().toString();
  const nonce = crypto.randomBytes(16).toString('hex');

  const bodyHash = crypto
    .createHash('sha256')
    .update(JSON.stringify(body) || '')
    .digest('hex');

  const data = `${timestamp}:${nonce}:${method}:${path}:${bodyHash}`;
  const signature = crypto
    .createHmac('sha256', token)
    .update(data)
    .digest('hex');

  return {
    'x-cli-signature': signature,
    'x-cli-timestamp': timestamp,
    'x-cli-nonce': nonce,
  };
}

Constraints

• Timestamps must be within 5 minutes of server time
• Each nonce can only be used once (tracked in Redis)
• Signing is optional — unsigned requests are allowed but logged

Listing Tokens

curl -H "Authorization: Bearer JWT_TOKEN" \
  https://api.controlinfra.com/api/auth/cli-tokens

Returns all tokens (names, scopes, creation dates) but not the token values.

Revoking a Token

curl -X DELETE -H "Authorization: Bearer JWT_TOKEN" \
  https://api.controlinfra.com/api/auth/cli-tokens/TOKEN_ID

Revoked tokens are immediately invalidated.

CI/CD Examples

GitHub Actions

env:
  CONTROLINFRA_TOKEN: ${{ secrets.CONTROLINFRA_TOKEN }}

steps:
  - name: Trigger drift scan
    run: |
      curl -X POST \
        -H "Authorization: Bearer $CONTROLINFRA_TOKEN" \
        https://api.controlinfra.com/api/scans/trigger/$REPO_CONFIG_ID

  - name: Check for drifts
    run: |
      curl -H "Authorization: Bearer $CONTROLINFRA_TOKEN" \
        "https://api.controlinfra.com/api/drifts/?status=detected&severity=high"

Controlinfra CLI

The Controlinfra CLI uses CLI tokens natively:

controlinfra auth login --token ci_abc123...
controlinfra scan trigger --repo my-repo
controlinfra drifts list --severity high

See the CLI documentation for more.