Developer Settings

This page explains the concepts. To turn it on step by step, follow the API-keys setup guide.

What You Configure Here

Developer settings give you control over how your application integrates with Recurso. From here you manage API keys, configure webhook endpoints, switch between test and production environments, and set tenant-level preferences.

API Keys

Create, rotate, and revoke live and test API keys

Environments

Isolated test and production environments with separate data

Webhooks

Configure endpoint URLs and event subscriptions

API Key Management

Every Recurso account has two environments, each with its own set of API keys:

Key Prefix	Environment	Purpose
`rsk_test_`	Test	Development and staging — no real charges
`rsk_live_`	Production	Live transactions with real payment processing

Live API keys (rsk_live_) process real payments. Never use live keys in development, CI pipelines, or client-side code.

Create an API Key

curl -X POST https://api.recurso.dev/v1/developer/keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Server — Production",
    "mode": "live"
  }'

Keys grant full tenant API access — there is no per-scope model today. mode is test (default, rsk_test_) or live (rsk_live_). Isolate blast radius by minting separate keys per service, not by scoping.

The full API key secret is returned only once at creation time. Store it securely in your secrets manager immediately. Recurso cannot retrieve it later.

List API Keys

curl https://api.recurso.dev/v1/developer/keys \
  -H "Authorization: Bearer $API_KEY"

Key revocation is a dashboard operation (Developers → API keys → Revoke) — there is no delete endpoint in the API yet.

Environment Management

Recurso provides fully isolated test and production environments. Data created in one environment is never visible in the other.

Test Environment

The test environment behaves identically to production with these differences:

Feature	Test	Production
Payment processing	Simulated (no real charges)	Real charges via Razorpay
Webhook delivery	Delivered to test endpoints	Delivered to production endpoints
API key prefix	`rsk_test_`	`rsk_live_`
Rate limits	Same as your plan tier	Same as your plan tier
Data retention	90 days	Unlimited

Use the test environment for integration testing, staging deployments, and webhook development. You can create test customers and subscriptions without triggering real payment flows.

Switching Environments

Environment is determined entirely by the API key used. There is no toggle or environment parameter — simply use the appropriate key:

// Test
const testClient = new Recurso({ apiKey: "rsk_test_..." });

// Production
const liveClient = new Recurso({ apiKey: "rsk_live_..." });

Tenant Configuration

Configure tenant-level settings that apply across your account:

curl -X PUT https://api.recurso.dev/v1/account \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme SaaS Pvt Ltd",
    "billing_email": "billing@acme.com",
    "default_currency": "INR",
    "timezone": "Asia/Kolkata",
    "invoice_prefix": "ACME",
    "auto_finalize_invoices": true,
    "payment_terms_days": 30
  }'

Configuration Options

Setting	Type	Description
`company_name`	string	Your company name, shown on invoices
`billing_email`	string	Reply-to address for billing emails
`support_url`	string	Customer support URL shown in the portal
`default_currency`	string	Default currency for new plans and invoices
`timezone`	string	IANA timezone for billing cycle calculations
`invoice_prefix`	string	Prefix for invoice numbers (e.g., `ACME-0001`)
`auto_finalize_invoices`	boolean	Automatically finalize invoices when generated
`payment_terms_days`	integer	Default payment terms in days (e.g., 30 = Net 30)

PUT /v1/account currently updates name and email only; the remaining options above are configured in the dashboard (Settings). Payment terms are set per subscription (payment_terms: net0|net15|net30|net60), not globally.

Webhook Endpoint Configuration

const endpoint = await recurso.webhooks.create({
  url: "https://api.acme.com/webhooks/recurso",
  events: [
    "subscription.created",
    "subscription.canceled",
    "payment.succeeded",
    "payment.failed",
    "invoice.paid"
  ]
});

curl -X POST https://api.recurso.dev/v1/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.com/webhooks/recurso",
    "events": [
      "subscription.created",
      "subscription.canceled",
      "payment.succeeded",
      "payment.failed",
      "invoice.paid"
    ],
    "environment": "live"
  }'

You can configure separate webhook endpoints for test and production environments. Test events are never sent to production endpoints and vice versa.

Key Rotation

Create a new key

Generate a new API key with the same scopes as the key you are replacing.

Deploy the new key

Update your application configuration or secrets manager with the new key. Deploy to all services that use it.

Verify traffic

Monitor the last_used_at field on both keys. Confirm the new key is handling all traffic.

Revoke the old key

Once no traffic is using the old key, revoke it. This is irreversible.

Best Practices

Never Expose Keys Client-Side

API keys belong in your backend. Never embed them in frontend code, mobile apps, or browser JavaScript.

Use Scoped Keys

Create separate keys per service with only the scopes each service needs. A reporting dashboard only needs read scopes.

Rotate Keys Regularly

Rotate API keys at least quarterly. Automate the process with your secrets manager.

Use Environment Variables

Store keys in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault), never in source code.

Monitor Key Usage

Review last_used_at timestamps to identify unused keys. Revoke keys that haven’t been used in 90+ days.

Separate Test and Live

Use distinct deployment pipelines for test and production. Never let a test key reach production infrastructure.

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

What You Configure Here

API Keys

Environments

Webhooks

API Key Management

Create an API Key

List API Keys

Environment Management

Test Environment

Switching Environments

Tenant Configuration

Configuration Options

Webhook Endpoint Configuration

Key Rotation

Best Practices

Never Expose Keys Client-Side

Use Scoped Keys

Rotate Keys Regularly

Use Environment Variables

Monitor Key Usage

Separate Test and Live

​What You Configure Here

API Keys

Environments

Webhooks

​API Key Management

​Create an API Key

​List API Keys

​Environment Management

​Test Environment

​Switching Environments

​Tenant Configuration

​Configuration Options

​Webhook Endpoint Configuration

​Key Rotation

​Best Practices

Never Expose Keys Client-Side

Use Scoped Keys

Rotate Keys Regularly

Use Environment Variables

Monitor Key Usage

Separate Test and Live

What You Configure Here

API Key Management

Create an API Key

List API Keys

Environment Management

Test Environment

Switching Environments

Tenant Configuration

Configuration Options

Webhook Endpoint Configuration

Key Rotation

Best Practices