CI/CD Integration & API Authentication

Run Clawkeeper scans in your pipeline and gate deployments on security grade.

API Key Setup

Create an API key

Go to Settings → API Keys in the Clawkeeper dashboard and create a key. Name it something descriptive like "GitHub Actions" or "CI Pipeline."

Copy the key immediately — it's only shown once. It starts with ck_live_.

Store the key as a secret

Never commit API keys to source control. Store the key as a CI secret:

GitHub Actions — Settings → Secrets → Actions → New repository secret → name it CLAWKEEPER_API_KEY
GitLab CI — Settings → CI/CD → Variables → add CLAWKEEPER_API_KEY (masked)
Other CI — Use your platform's secret management to expose CLAWKEEPER_API_KEY as an environment variable

GitHub Actions Workflow

Add a scan step to your workflow

This workflow installs Clawkeeper, runs a scan, and uploads results to the dashboard. It fails the job if the grade drops below B.

.github/workflows/security-scan.yml

name: Security Scan

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * *'   # daily at 6 AM UTC

jobs:
  clawkeeper:
    runs-on: ubuntu-latest
    steps:
      - name: Install Clawkeeper
        run: curl -fsSL https://clawkeeper.dev/install.sh | bash

      - name: Run security scan
        env:
          CLAWKEEPER_API_KEY: ${{ secrets.CLAWKEEPER_API_KEY }}
        run: |
          clawkeeper.sh scan --report /tmp/scan.txt
          clawkeeper.sh agent run

      - name: Upload report artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: clawkeeper-report
          path: /tmp/scan.txt

Grade gating

The clawkeeper.sh scan command exits with code 0 regardless of grade, so your pipeline won't fail on low grades by default. To enforce a minimum grade, parse the report output and add a grade check step.

Scan Upload API

Understand the API endpoint

The agent handles API communication for you, but if you need direct integration, the scan upload endpoint is:

$ POST https://clawkeeper.dev/api/v1/scans

Authorization: Bearer ck_live_...

The request body is JSON with these fields:

Field	Type	Description
hostname	string	Machine hostname (required)
platform	string	"macos" or "linux" (required)
score	number	0–100 (required)
grade	string	A, B, C, D, or F (required)
checks	array	Array of {status, check_name, detail} objects (required)
passed	number	Count of passed checks
failed	number	Count of failed checks
os_version	string	OS version (optional)
scanned_at	string	ISO 8601 timestamp (optional, defaults to now)

Authentication

All API requests require a Bearer token in the Authorization header. Keys are SHA-256 hashed server-side — the raw key is never stored.

Example: curl

curl -X POST https://clawkeeper.dev/api/v1/scans \
  -H "Authorization: Bearer ck_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "ci-runner-01",
    "platform": "linux",
    "score": 85,
    "grade": "B",
    "passed": 33, "failed": 6, "fixed": 0, "skipped": 0,
    "checks": [
      {"status": "PASS", "check_name": "firewall", "detail": "UFW active"},
      {"status": "FAIL", "check_name": "filevault", "detail": "Not enabled"}
    ]
  }'

A successful response returns:

Response (200)

{
  "ok": true,
  "host_id": "uuid-...",
  "scan_id": "uuid-..."
}

Use the agent instead of raw API

For most CI/CD setups, running clawkeeper.sh agent run is simpler than calling the API directly. The agent handles payload formatting, error retries, and version reporting automatically.

Error Handling

Common API errors

Status	Error	Fix
401	Invalid API key	Check your key starts with ck_live_ and hasn't been deleted
400	Validation error	Check required fields (hostname, platform, score, grade, checks)
403	Host limit reached	Upgrade your plan or remove unused hosts from the dashboard
413	Payload too large	Request body must be under 5 MB

Automate these checks with Clawkeeper

One command scans your entire OpenClaw deployment and gives you an A-F security grade.