Authentication & Environments

The RevKeen API uses API keys and a clear environment model so you can safely build, test, and deploy billing integrations.

This page covers:

• How authentication works (via Unkey)
• Key formats and prefixes
• Available environments (Live, Sandbox, Mock)
• How rate limits are enforced
• How to use the API Playground on this site to try the API

1. Authentication Overview

All requests to the RevKeen API are authenticated with an API key passed in the x-revkeen-key header.

RevKeen uses Unkey under the hood to issue, manage, and rate-limit these keys.

x-revkeen-key: rk_live_your_api_key

If the header is missing or invalid, the API responds with:

• 401 Unauthorized
• An authentication_error body as defined in the Error schema

2. Key Types & Prefixes

API keys are generated from the RevKeen Dashboard → Developers → API Keys page.

Each key has:

• A prefix (indicating environment)
• A random secret (the sensitive part)
• Associated metadata (tenant, rate plan, roles) managed by Unkey

2.1 Key prefixes

3. Environments

RevKeen exposes three environments, all defined in the OpenAPI spec (revkeen-v1.yaml):

3.1 Live

Use Live for:

• Real customers
• Real transactions through NMI
• Production integrations

GET /customers
Host: api.revkeen.com
x-revkeen-key: rk_live_123...

3.2 Sandbox

Use Sandbox for:

• Development and staging environments
• Automated tests
• Integration trials with your own systems

Sandbox uses:

• Separate data from Live
• The same API surface and validation
• The rk_sandbox_ key prefix

GET /customers
Host: sandbox-api.revkeen.com
x-revkeen-key: rk_sandbox_123...

3.3 Mock

The Mock environment is backed by the Scalar mock server and uses only the OpenAPI specification:

• No persistence
• No real side effects
• Deterministic sample responses

Use it when:

• You want to prototype quickly
• You're building a UI without real data
• You're validating request/response shapes

4. Making Authenticated Requests

4.1 Example with curl

curl https://api.revkeen.com/v1/customers \
  -H "x-revkeen-key: rk_live_123..." \
  -H "Content-Type: application/json"

4.2 Example with the TypeScript SDK (Speakeasy)

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

const rk = new RevKeenClient({
  apiKey: process.env.REVKEEN_API_KEY!,   // rk_live_ or rk_sandbox_
  environment: "live",                     // or "sandbox"
});

const customers = await rk.customers.list({
  page: 1,
  limit: 20,
});

5. Rate Limits

Rate limiting is enforced per API key via Unkey. From the spec:

Each response contains the headers:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset (Unix timestamp)

When a limit is exceeded, the API returns 429 Too Many Requests with a rate_limit_error body.

6. API Playground (Try the API)

You can try the API directly from this documentation using the built-in API Playground:

1. Go to the API Reference page.
2. Click on any endpoint, for example GET /customers.
3. In the Try it panel:
   • Select the environment (Live, Sandbox, or Mock)
   • Under Headers, set x-revkeen-key: rk_sandbox_...
4. Click Send to see the live response.

7. Choosing the Right Environment

Use this as a rule of thumb:

• Local dev / staging → Sandbox
• QA / client demos → Sandbox or Mock
• Production → Live

Architecture-wise:

• All environments share the same OpenAPI spec
• All are protected by Unkey
• SDKs and docs automatically respect your chosen environment

8. Next Steps