Authentication

The recv developer API (https://recv.money/v1) authenticates every request with an API key. Keys are created in the Developer Portal and belong to a single workspace.

API access requires a plan that includes the API. The Developer and Business plans include it; Trial and Merchant do not. A key on a plan without API access receives 403 Forbidden.

Passing the key

Send the key in either header — both are accepted:

# Preferred
curl https://recv.money/v1/me -H "X-API-Key: $RECV_API_KEY"

# Also supported
curl https://recv.money/v1/me -H "Authorization: Bearer $RECV_API_KEY"

If both are present, X-API-Key is used.

Environments: test vs live

Each key is bound to one environment, encoded in its prefix:

The environment of a created invoice follows the key that created it — there is no mode field in the request body. Keep separate test_ and live_ keys, and never use a live key for tests.

Scopes

Keys carry one or both of these scopes:

If you create a key without specifying scopes, it gets both by default. A call that requires a scope the key lacks returns 403 with an error such as API key scope invoices:write is required. (GET /v1/me requires no scope.)

Inspecting the current key

GET /v1/me returns the workspace, plan, current usage, and the key's own metadata:

curl https://recv.money/v1/me -H "X-API-Key: $RECV_API_KEY"

{
  "key": {
    "id": 7,
    "label": "Server key",
    "prefix": "live_b3c4",
    "environment": "live",
    "scopes": ["invoices:read", "invoices:write"]
  },
  "usage": { "monthly_requests": 128, "monthly_limit": 50000 }
}

Security best practices

• Server-side only. Never ship a key in browser, mobile, or client code, or commit it to a repository.
• Use environment variables. Store the secret in RECV_API_KEY or your platform's secret manager.
• Rotate on suspicion. Revoke a compromised key in the Developer Portal and issue a new one. The full secret is shown only once at creation.
• Separate environments. Use distinct test_ and live_ keys.

Example (Node.js)

const response = await fetch("https://recv.money/v1/me", {
  headers: { "X-API-Key": process.env.RECV_API_KEY }
});
const data = await response.json();