API Keys

Create and revoke programmatic API keys.

API keys (cifp_...) authenticate programmatic access to the CIFP control plane API. Each key carries explicit permission scopes — a key without the required scope receives 403 Missing required scope: <scope> even if it is otherwise valid. Session-authenticated users (browser dashboard) are implicitly granted all scopes.

Managing Keys in the Dashboard

The API Keys page in the dashboard (/dashboard/api-keys) provides a full UI for:

Listing all keys with scope chips, status badges, and last-used dates
Creating a new key — name, scope checkboxes, optional expiry date picker
Copying the raw key value (shown once on creation, never again)
Revoking a key with a single click
Configuring expiry notifications (see below)

List API Keys

GET/api/keys

Requires scope: keys:read (or session auth).

bash

curl https://cifp.vril.dev/api/keys \
  -H "Authorization: Bearer cifp_your_api_key"

Response

{
  "keys": [
    {
      "id":         "key_abc123",
      "name":       "ci-pipeline",
      "keyPrefix":  "cifp_abc1",
      "scopes":     ["proxies:read", "secrets:write"],
      "lastUsedAt": "2026-06-05T10:00:00Z",
      "expiresAt":  "2027-01-01T00:00:00Z",
      "createdAt":  "2026-06-01T10:00:00Z",
      "revokedAt":  null
    }
  ],
  "count": 1
}

Key hashes and plaintext values are never returned.

Create API Key

POST/api/keys

Requires scope: keys:write (or session auth).

bash

curl -X POST https://cifp.vril.dev/api/keys \
  -H "Authorization: Bearer cifp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name":      "ci-pipeline",
    "scopes":    ["proxies:read", "secrets:write"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

Response (201)

{
  "id":        "key_abc123",
  "name":      "ci-pipeline",
  "keyPrefix": "cifp_abc1",
  "scopes":    ["proxies:read", "secrets:write"],
  "key":       "cifp_abc1def2...",
  "expiresAt": "2027-01-01T00:00:00Z",
  "createdAt": "2026-06-06T09:00:00Z"
}

Save the key immediately

The key field is only present in the creation response. It is stored as a SHA-256 hash and cannot be recovered. Revoke and regenerate if lost. The dashboard shows it in a copy-once dialog for the same reason.

Permission Scopes

Scopes are enforced on every API request authenticated with a cifp_... key. Specify the minimum scopes your integration needs. A key missing a required scope receives 403 with the message Missing required scope: <scope>.

Scope	Permits
`proxies:read`	List and get proxy details
`proxies:write`	Create, update, and delete proxies
`secrets:read`	List secret metadata (values are never returned)
`secrets:write`	Create and delete secrets
`credentials:read`	List proxy credential metadata
`credentials:write`	Create and revoke proxy credentials
`rules:read`	List CEL firewall rules
`rules:write`	Create, update, and delete firewall rules
`logs:read`	Query access logs
`keys:read`	List your own API keys
`keys:write`	Create and revoke API keys

Revoke API Key

DELETE/api/keys/:id

Requires scope: keys:write (or session auth).

Sets revokedAt on the key. Any subsequent request using this key immediately receives 401 API key has been revoked. The record remains visible in list responses with its revokedAt timestamp.

bash

curl -X DELETE https://cifp.vril.dev/api/keys/key-abc123 \
  -H "Authorization: Bearer cifp_your_api_key"

# Returns 204 No Content

Expiry Notifications

CIFP can notify you by email and/or SMS before any of your API keys expire — using the same lead-time values as per-proxy secret notifications. This is a separate, account-wide system: it covers only API keys, not secrets or proxy credentials.

Notification preferences are configured account-wide on the API Keys → Expiry Notifications section of the dashboard. They are stored per-tenant and checked on a recurring schedule.

Get notification settings

GET/api/account/notifications

bash

curl https://cifp.vril.dev/api/account/notifications \
  -H "Authorization: Bearer cifp_your_api_key"

Response

{
  "enabled":   true,
  "email":     "you@example.com",
  "phone":     "+15558675309",
  "leadTimes": ["1w", "1d"]
}

Update notification settings

PUT/api/account/notifications

bash

curl -X PUT https://cifp.vril.dev/api/account/notifications \
  -H "Authorization: Bearer cifp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled":   true,
    "email":     "you@example.com",
    "phone":     "+15558675309",
    "leadTimes": ["2w", "1w", "1d"]
  }'

Response (200)

{ "ok": true }

Accepted leadTimes values: "2w", "1w", "5d", "3d", "2d", "1d". At least one must be included.

Checks run roughly once per hour. Unlike per-proxy secret notifications — which never send duplicates for the same (item, lead-time, channel) combination — account-wide API key notifications may occasionally send the same alert more than once across consecutive checks. If you notice repeated alerts for a key that hasn't changed, this is expected behavior rather than a bug.