API Keys

API keys are created in the API & Webhooks tab. The real form in the app asks for a key name, one or more scopes, and an optional expiry window in days. The backend accepts expiry values from 1 to 3650 days and returns the plaintext credential only at creation or rotation time.

Supported scopes

Example: create a scoped key from an authenticated admin session.

curl -X POST https://api.actloom.com/api/settings/api-keys \
  -H "Content-Type: application/json" \
  -b "your_session_cookie_here" \
  -d '{
    "companyId": "your_company_id",
    "name": "CI integration key",
    "scopes": ["read:reports", "write:reports"],
    "expiresInDays": 365
  }'

Settings API Endpoints

These endpoints back the actual settings page. They are useful when your internal admin tooling needs to bootstrap API keys, manage webhook endpoints, or orchestrate provider connections through a signed-in operator session.

How the integrations tab behaves in the app

Ready-made artifacts shipped with the app:

Webhooks

Webhooks are configured in the same API & Webhooks tab. The real form captures endpoint URL, description, and a set of subscribed events. Each saved endpoint then exposes controls to test delivery, switch between active and disabled, and delete the endpoint entirely.

Supported event types

Example: create a webhook endpoint from an authenticated admin session.

curl -X POST https://api.actloom.com/api/settings/webhooks \
  -H "Content-Type: application/json" \
  -b "your_session_cookie_here" \
  -d '{
    "companyId": "your_company_id",
    "url": "https://your-app.example.com/webhooks/actloom",
    "description": "Production endpoint",
    "events": ["incident.created", "report.generated"]
  }'

Data portability examples

curl -H "Authorization: Bearer actloom_..." \
  "https://api.actloom.com/api/v1/assessments/export?format=csv&aiSystemId=sys_123"

curl -X POST https://api.actloom.com/api/v1/ai-systems/import \
  -H "Authorization: Bearer actloom_..." \
  -H "Content-Type: text/csv" \
  --data-binary @systems.csv

Webhook Test Payload

The Test action in the webhook table, or POST /api/settings/webhooks/{id}/test, sends a real request to the configured endpoint and records the result. This is the fastest way to validate receiver reachability, timeout behavior, and basic request parsing before you depend on live events.

Delivery headers

Content-Type: application/json
x-actloom-event: webhook.test
x-actloom-delivery-id: evt_test_<timestamp>

The current test route does not include an HMAC signature header even though endpoint creation returns a signing secret.

Request body

{
  "id": "evt_test_1700000000000",
  "type": "webhook.test",
  "createdAt": "2026-03-01T12:00:00.000Z",
  "data": {
    "endpointId": "wh_123",
    "companyId": "company_123"
  }
}

Release Gates

The Smart Release Gate API lets CI/CD pipelines ask ActLoom a single question before shipping: “is this AI system cleared to deploy to preview, staging, or production?” Instead of a binary allow/block, the gate returns a tiered decision so teams can ship to lower environments while still closing gaps for production.

What the response tells the pipeline

Evaluate the gate for a deployment

curl -H "Authorization: Bearer actloom_..." \
  "https://api.actloom.com/api/v1/release-gates?aiSystemId=sys_123&environment=production"

# Response
{
  "status": "allow",
  "allow": true,
  "gate": { /* legacy fields preserved */ },
  "smartGate": {
    "tier": "allow_staging",
    "maxAllowedEnvironment": "staging",
    "allowRequested": false,
    "readinessPct": 87,
    "topGaps": [
      {
        "requirementName": "Red-team testing before deployment",
        "articleReference": "Art. 15",
        "priority": "HIGH",
        "effortDays": 2,
        "impact": "unblocks_production"
      }
    ],
    "estimatedDaysToProduction": 5,
    "canOverride": true,
    "overrideWindowHours": 48,
    "explanation": "Cleared for staging only (87% readiness). Close top gaps to reach production."
  }
}

Time-boxed overrides

When a system is blocked but the team needs to ship a hotfix, authorized operators can grant a 48-hour maximum override. Every override is persisted in Vercel KV with auto-expiry, logged to the audit trail, and emits a release_gate.overridden webhook so reviewers and on-call engineers are notified.

Grant an override

curl -X POST https://api.actloom.com/api/v1/release-gates/override \
  -H "Authorization: Bearer actloom_..." \
  -H "Content-Type: application/json" \
  -d '{
    "aiSystemId": "sys_123",
    "targetEnvironment": "production",
    "reason": "Hotfix for login regression, remediation task rem_42 in flight",
    "windowHours": 24
  }'

# Response
{
  "override": {
    "overrideId": "ov_1700000000000_ab12cd",
    "grantedAt": "2026-04-20T09:12:00.000Z",
    "expiresAt": "2026-04-21T09:12:00.000Z",
    "grantedBy": "user_alice",
    "reason": "Hotfix for login regression, remediation task rem_42 in flight"
  },
  "smartGate": { /* re-evaluated gate state */ }
}

GitHub Actions example

A minimal pre-deploy job that fails the pipeline when the smart gate does not clear the requested environment, and posts the explanation to the Actions summary:

# .github/workflows/deploy.yml
- name: ActLoom release gate
  env:
    ACTLOOM_API_KEY: ${{ secrets.ACTLOOM_API_KEY }}
  run: |
    RESP=$(curl -sS \
      -H "Authorization: Bearer $ACTLOOM_API_KEY" \
      "https://api.actloom.com/api/v1/release-gates?aiSystemId=sys_123&environment=production")

    ALLOW=$(echo "$RESP" | jq -r '.smartGate.allowRequested')
    TIER=$(echo "$RESP" | jq -r '.smartGate.tier')
    WHY=$(echo "$RESP" | jq -r '.smartGate.explanation')

    echo "### ActLoom Release Gate" >> "$GITHUB_STEP_SUMMARY"
    echo "- **Tier:** \`$TIER\`" >> "$GITHUB_STEP_SUMMARY"
    echo "- **Reason:** $WHY" >> "$GITHUB_STEP_SUMMARY"

    if [ "$ALLOW" != "true" ]; then
      echo "::error::Release gate blocked: $WHY"
      exit 1
    fi

GitLab CI example

# .gitlab-ci.yml
release_gate:
  stage: pre-deploy
  image: curlimages/curl:latest
  script:
    - |
      ALLOW=$(curl -sS \
        -H "Authorization: Bearer $ACTLOOM_API_KEY" \
        "https://api.actloom.com/api/v1/release-gates?aiSystemId=sys_123&environment=$CI_ENVIRONMENT_NAME" \
        | jq -r '.smartGate.allowRequested')
      test "$ALLOW" = "true" || exit 1