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, expired, revoked, or belongs to the wrong environment, the API returns 401 Unauthorized with type: authentication_error and a WWW-Authenticate: Bearer realm="revkeen-api" challenge header. A key that authenticates but lacks the scope for the endpoint returns 403 with type: authorization_error. See Errors for the full code vocabulary and the 429 rate-limit headers.

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). Scopes intersect the caller's team-role grants — they are not a separate permission system, and they never add access the role does not already have. An empty scope set grants nothing. A request that calls an endpoint outside the key's scopes is rejected with 403 and code: insufficient_permissions — 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, type: authorization_error 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. Access tokens are opaque and prefixed rkoa_, sent as Authorization: Bearer rkoa_*.

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"],
  },
  baseUrl: "https://api.revkeen.com/v2",
});

const customers = await client.customers.list({ limit: 10 });

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

Next Steps

API key usage

In Settings → Developer → API Keys, select Usage beside a key to view its last 24 hours, 7 days or 30 days of recorded authentication activity. The view includes accepted, authentication-rejected and rate-limited counts, verification errors, p50/p95 verification latency and endpoint-family breakdowns. It remains available for revoked keys.

Verification latency measures authentication, not the complete API response. Activity that cannot be securely attributed to your key is excluded; a rejected request may therefore be absent if the key has no previously verified binding. Historical analytics starts when collection is enabled and is not a billing record. If collection or the analytics service is unavailable, the view reports that state separately from a window with no recorded verifications.

Credential and authority matrix

Better Auth handles credential authentication; possessing a valid credential does not grant every action. The same merchant/action remains subject to Engine authorization and data isolation across REST, SDK, CLI, and MCP. Machine clients cannot bypass actions restricted to human confirmation or step-up.

During migration, identify the credential type and environment first, then test a bounded read, a denied read, expiry/revocation, and rate limiting. 401 means authentication failed, 403 means the authenticated request lacks access, and 429 means rate limiting. Preserve WWW-Authenticate, Retry-After, request IDs, and rate-limit metadata for your error handler; redact credentials and personal data from diagnostics.

The published SDK and CLI may lag current source. Use the release availability guide before adopting newer OAuth/request-option helpers.

Owner: david · Reviewed 30 Sep 2026 · Next review 30 Oct 2026