Authentication

All API requests require authentication via the X-SECRET-KEY HTTP header:

The secret key determines the platform and environment (live or test). Without X-ACCOUNT-ID, requests operate on that same account.

Start in Sandbox

For a new integration, open Configuración → Llaves API → Abrir Sandbox and choose Crear mi llave TEST. Follow First test payment. TEST keys only exist inside a Sandbox: your live account holds LIVE keys only. GET /test returns environment (sandbox or live) and sandbox_id to confirm it. No publishable key is required.

Personal and business accounts

Both personal and business accounts can generate TEST and LIVE API keys in Settings → API Keys. The Sandbox above is for business accounts; a personal account tests with its TEST key. Account administrators can manage keys; other team roles do not gain access through this change.

Either type can be the platform or an existing connected child account. To connect an existing personal account, use the platform’s invitation link and explicitly select the personal account. The platform uses its own key with X-ACCOUNT-ID; the recipient does not need to share or generate a key.

API access does not change account verification, processing limits, installment eligibility, or key permissions for moving money. Supporting an account type does not automatically approve a platform’s use case.

Connected account context

If the key belongs to a platform, add X-ACCOUNT-ID to execute a request inside a connected child, like Stripe-Account in Stripe Connect:

curl https://app.recurrente.com/api/intents \
  -H "X-SECRET-KEY: sk_live_xyz789..." \
  -H "X-ACCOUNT-ID: ac_child123"

The platform can list, retrieve, and manage API resources belonging to that child regardless of whether the platform or the child created them. The context covers checkouts, customers, products, subscriptions, intents, payment intents, refunds, balances, transfers, and other account-owned resources.

Only accounts directly connected to the API-key owner are accepted. Access is not transitive to accounts connected to the child. Endpoints under /connected_accounts remain platform operations and take the child ID in the path. Endpoints that already accept account_id keep it as a compatibility alias. Key capabilities, account verification, and money-movement destination restrictions still apply inside the connected context.

Public and private keys

The private key (also called the secret key) is sent in X-SECRET-KEY. Older integrations used a public key in X-PUBLIC-KEY; the current API no longer uses that header for authentication. Keep the private key on your server, never in browser code or a public repository.

Finding Your Keys

To find your API Keys, within your Recurrente account, go to:

Settings → API Keys.

1. Log in to the Recurrente Dashboard
2. Go to Settings → API Keys
3. Copy your secret key. It is only shown in full when generated or rotated.

Live and Sandbox

Each account has one environment, and every key it holds belongs to it:

• Live keys (sk_live_) — Live on your live account. Real transactions are processed.
• Test keys (sk_test_) — Live only inside a Sandbox. No real money is moved.

The API endpoint is the same for both. The secret key determines which environment you’re operating in.

Live accounts used to have a TEST key of their own. Those keys were retired: an sk_test_ key that no longer exists answers 401 with a message pointing to the Sandbox. The test objects (live_mode: false) they created stay on the account, but a live key never lists or resolves them (404, or 401 on /customers).

Example Request

curl https://app.recurrente.com/api/test \
  -H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY"

Authentication Error

If your API keys are not being sent or are invalid, you will receive an HTTP 401 Unauthorized response code:

{
  "message": "Autenticación Errónea 👀",
  "errors": {
    "authentication": [
      "Las llaves de API son inválidas o no coinciden."
    ]
  }
}

Environments