Skip to content
Authentication

Authentication

Send the key in the x-api-key header. A bearer token is also accepted: Authorization: Bearer <key>. Pick one form and use it everywhere.

Send a key

bash
curl https://api.rollstamp.example/v1/ping \
  -H "x-api-key: $ROLLSTAMP_API_KEY"

A missing key returns 401 missing_api_key. A key that is not recognized returns 403 invalid_api_key; a disabled or cancelled key returns 403 key_disabled. A key with no registered server addresses returns 403 ip_whitelist_required, and a call from an address outside the allowlist returns 403 ip_not_allowed. Repeated bad keys from one address can trigger 429 too_many_auth_failures.

Sandbox keys

The tester lists four demo keys. The standard key fflsbx_std_9f3k2m7q4t and the pro key fflsbx_pro_4h8w1z6c2r accept calls from 127.0.0.1 or ::1; the pro key also accepts 203.0.113.25. They hold sample data. The other two show IP allowlist states: one allows only 198.51.100.7 and one has no server addresses registered. None are live credentials.

Keep keys out of the browser and out of git. Read the key from the server environment. If a key leaks, stop using it and ask for it to be disabled and replaced; do not reuse it.

The MCP connector

The connector's normal sign-in is OAuth 2.1 with PKCE, and a token goes in the Authorization header. An MCP client on an allowlisted machine can also send an account API key in that header. An account can leave the connector off, and a bulk change is previewed before it is applied. See the connector page.