Crowdsec Service API

CrowdSec Service API (SAPI) — cloud blocklist / allowlist / integration automation

SAPI is the premium REST API behind the CrowdSec Console. It manages cloud-side objects (private blocklists, allowlists, decisions, firewall integrations) that then push down to enrolled engines and bouncers. It is not the local engine API — there is no cscli here, only HTTPS.

• Base URL: https://admin.api.crowdsec.net/v1
• Auth: x-api-key: <key> header on every call. (One exception: the integration content endpoint uses HTTP Basic with credentials minted at integration creation — see references/integrations.md.)
• Interactive API docs: https://admin.api.crowdsec.net/v1/docs · spec https://admin.api.crowdsec.net/v1/openapi.json

Boundary — this skill vs the crowdsec skill

Cloud allowlists/blocklists here only take effect on an engine once that engine is enrolled and subscribed to the list. The enrollment half lives in the crowdsec skill.

Operating contract

Every call here hits production and can change what subscribed engines enforce.

1 — Resolve the key. Never echo it, never write it anywhere but the file below:

KEY="${CROWDSEC_SAPI_KEY:-$(cat ~/.config/crowdsec/sapi_key 2>/dev/null)}"
[ -n "$KEY" ] || echo "No key: export CROWDSEC_SAPI_KEY or store it in ~/.config/crowdsec/sapi_key (chmod 0600)"

2 — Validate before acting — one read call confirms the key and shows which tenant is about to change:

curl -s -H "x-api-key: $KEY" https://admin.api.crowdsec.net/v1/info
# → {"organization_id":"…","subscription_type":"…","api_key_name":"…"}

3 — Classify read vs mutate. GET / download / POST …/search are safe — run them directly. Every POST / PATCH / DELETE that changes state requires explicit confirmation first: present the exact URL and JSON body, then wait for a yes.

4 — Extra-danger operations — spell out the consequence in plain words before the confirm, because subscribed engines enforce these lists, so a change can block or unblock real traffic and is hard to undo:

5 — Clean up any object created only to test a recipe. A key that was exposed anywhere in transit must be rotated.

Step — Detect the intent

Step — curl cheat sheet

All assume KEY is set (see operating contract). jq optional for readability.

where B=https://admin.api.crowdsec.net/v1.

Hard don'ts

• Don't send a mutating call before the URL + body have been shown and approved (see operating contract §3–4).
• Don't use …/ips/bulk_overwrite when the user means "add a few IPs" — that's …/ips. bulk_overwrite wipes the list first.
• Don't print, log, or persist the API key anywhere but ~/.config/crowdsec/sapi_key. Resolve it from there or from the env var only.
• Don't assume a cloud allowlist/blocklist is enforced just because the API call succeeded — the engine must be enrolled and subscribed, and it pulls on a poll cycle (verify locally via the crowdsec skill).

Docs

Canonical: https://docs.crowdsec.net/u/console/service_api/getting_started. Each references/ file cites the specific upstream page and the live OpenAPI operation it derives from.