Authentication

RevKeen supports two authentication methods: API keys for server-to-server integrations and OAuth 2.1 for MCP hosts, third-party apps, and automated workflows.

API keys (recommended for most integrations)

Use your RevKeen API key in the x-api-key header on every server-side REST request.

Auth method

x-api-key: rk_live_your_api_key

Both x-api-key: rk_live_* and Authorization: Bearer rk_live_* are accepted — use whichever your HTTP client makes easiest.

If the header is missing, invalid, revoked, or belongs to the wrong environment, the API returns 401 Unauthorized.

Where to get keys

Create and manage API keys in the RevKeen Dashboard → Settings → Developer.

Create separate keys for:

• production services
• staging and QA
• each integration or backend service that needs isolated access

When you create a key, assign it the minimum scopes it needs (for example, a reporting integration only needs *:read scopes). Scopes are enforced on every request — see Key lifecycle & security below.

Staging vs live

Example

curl https://staging-api.revkeen.com/v2/customers \
  -H "x-api-key: rk_sandbox_your_api_key" \
  -H "Accept: application/json"

Server-side key safety

• Keep API keys in environment variables or a secret manager.
• Never ship live keys to browsers, mobile apps, screenshots, or public repositories.
• Give each key the least scope it needs, and revoke keys that are no longer used.
• Keep staging and production credentials fully separate.

Key lifecycle & security

RevKeen keys are full-lifecycle — scoped, rotatable, IP-lockable, and audited. All of the controls below are managed per key in Settings → Developer.

Scopes

Every key carries a set of scopes (for example customers:read, invoices:write). A request that calls an endpoint outside the key's scopes is rejected with 403 — a read-only key can never move money, even if the secret leaks. Grant the narrowest scopes that get the job done.

IP allowlists

Restrict a key to specific source IPs or CIDR ranges (IPv4 and IPv6). A request from any other address is rejected with 403 and code: IP_NOT_ALLOWED.

• An empty allowlist means unrestricted — the default, no behaviour change.
• Ideal for server-side keys that only ever call from your backend's fixed egress IPs.
• The source IP is determined from the real client connection (Cloudflare-verified), not from a client-supplied header, so the restriction can't be spoofed.

Rolling (zero-downtime rotation)

Roll a key to mint a new secret with the same scopes while the old secret keeps working for a grace window (default 24 hours, configurable 1–168h). Deploy the new secret to your services during the window, then let the old one expire automatically — no downtime, no race.

Last used

The key inventory shows the last-used timestamp for every key, and flags keys unused for 90+ days as stale. Use it to spot and prune forgotten or leaked keys with confidence.

Audit trail

Key lifecycle events — created, rolled, revoked — are recorded with the acting user and timestamp, so you always have a queryable history of who changed which key and when.

Revocation

Revoking a key takes effect immediately and durably across the whole platform — a revoked key stops authenticating right away and stays blocked through restarts and infrastructure events. Revocation cannot be undone; roll instead if you only need to rotate the secret.

OAuth 2.1

For MCP integrations, third-party apps, and automated workflows, use OAuth 2.1 with Authorization: Bearer rk_oauth_* tokens.

import { RevKeenClient } from '@revkeen/sdk';

const client = new RevKeenClient({
  oauth: {
    clientId: process.env.REVKEEN_CLIENT_ID!,
    clientSecret: process.env.REVKEEN_CLIENT_SECRET!,
    scopes: ['customers:read', 'invoices:read'],
  },
});

See the OAuth 2.1 guide for authorization code + PKCE, client credentials, dynamic client registration, and scope reference.

Next Steps