Skip to content

Authentication

Protected endpoints accept one of two credential types. Prefer an API key for machine-to-machine integrations; use a Bearer ID token for interactive clients that already sign in with email/password.

Credential methods

Header Format Notes
X-API-Key rev_<12hex>.<32hex> Long-lived key issued from the Revolutio platform. Prefer this for server integrations.
Authorization Bearer <Firebase ID token> Short-lived token from POST /authenticate (or Firebase Auth). Expires after 1 hour.

Warning

Do not put API keys in Authorization. Keys are accepted only via X-API-Key. Putting rev_… in the Bearer header is rejected.

When both headers are present, X-API-Key wins.

Example headers

X-API-Key: rev_a1b2c3d4e5f6.0123456789abcdef0123456789abcdef

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Obtain an ID token

Request

POST https://api.revolutio.systems/authenticate
Content-Type: application/json

Body

{
  "email": "your-email@example.com",
  "password": "your-password"
}
Field Type Required Description
email string Yes Registered account email
password string Yes Account password

Response

{
  "idToken": "eyJhbGciOiJSUzI1NiIs..."
}
Field Type Description
idToken string Firebase ID token for subsequent calls (≈ 1 hour TTL) 
{
  "error": "Email and password must be provided"
}

{
  "error": "INVALID_PASSWORD"
}

{
  "error": "Too many attempts. Try again later."
}

Returned after 5 failed login attempts within 1 hour for the same email.

API keys

API keys are created and managed in the Revolutio product (account settings). The plaintext key is shown once at creation; store it in a secrets manager.

Property Detail
Format rev_<keyId>.<secret>
Header X-API-Key
Scope Acts as the owning user (same credits, subscription, ownership rules)
Revocation Revoked keys fail auth immediately with 401

Info

Keys are hashed at rest. Revolutio never stores the full plaintext after creation.

Using credentials

cURL: API key

export REV_API_KEY="rev_xxxxxxxxxxxx.yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

curl -sS -X POST https://api.revolutio.systems/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $REV_API_KEY" \
  -d '{"identifier": "09215191", "jurisdiction": "GB"}'

cURL: ID token

TOKEN=$(curl -sS -X POST https://api.revolutio.systems/authenticate \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}' \
  | jq -r '.idToken')

curl -sS -X POST https://api.revolutio.systems/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"identifier": "09215191", "jurisdiction": "GB"}'

Common auth errors

Status Body Cause
401 Missing Authorization or X-API-Key header No credentials sent
401 Invalid or expired token Bad/expired ID token, wrong key, or revoked key
403 Your account access has been suspended… Account locked (access_locked)

See Error Handling for the full status catalogue.