Keys and authentication

01What a key looks like

A working key consists of the prefix rg_live_ followed by 40 more characters. It is shown in full only once, when you create it. We store only its fingerprint, so a lost key cannot be recovered—create a new one.

rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

02How to pass a key

Either of two headers will do, one per request: Authorization: Bearer <key> or X-API-Key: <key>. If both are sent, the non-empty Bearer applies; if the Bearer is invalid, the other header is not checked.

To check a key, use a balance request: it charges nothing.

# Option 1: the Authorization header
curl --fail-with-body --max-time 20 \
  https://api.rendergrid.io/api/public/v1/balance \
  -H "Authorization: Bearer $RENDERGRID_API_KEY"

# Option 2: the X-API-Key header
curl --fail-with-body --max-time 20 \
  https://api.rendergrid.io/api/public/v1/balance \
  -H "X-API-Key: $RENDERGRID_API_KEY"

import os
import requests

key = os.environ["RENDERGRID_API_KEY"]
response = requests.get(
    "https://api.rendergrid.io/api/public/v1/balance",
    headers={"Authorization": f"Bearer {key}"},
    timeout=(5, 20),
)
response.raise_for_status()
print(response.json())

// Node.js 22+, .mjs file
const url = "https://api.rendergrid.io/api/public/v1/balance";
const key = process.env.RENDERGRID_API_KEY;
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${key}` },
  signal: AbortSignal.timeout(20_000),
});
if (!response.ok) {
  const body = await response.text();
  throw new Error(`HTTP ${response.status}: ${body}`);
}
console.log(await response.json());

{
  "currency": "USD",
  "balance": "42.5000",
  "overdraft_limit": "0.0000",
  "available": "42.5000"
}

03Create, replace, revoke

1. Create a key

   In the portal, in the “API keys” section, click “Create key”. Name it after the integration: “website,” “bot,” “warehouse.” That makes it easier to tell whose key it is.

2. Copy it right away

   After you close the window, the key cannot be shown again. Put it in an environment variable or in a secret store.

3. Replace it without downtime

   Create a new key, put it in your integration, check one request, and only then revoke the old key. A revoked key stops working immediately.

The balance and limits of an account are shared by all of its keys. Separate keys exist so that you can change and revoke access for each integration independently.

An account can have up to 50 active keys. Keys that Playground issues for the length of your session do not count toward this limit. A replaced key still counts until it expires.

You can set each key its own monthly spending limit. It is a hard cap for that key: when it is used up, requests with that key get 402 (learn more).

04What the API responds

Read the reason for a refusal from error.code and error.details.reason, not from the message text.

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "ERR_API_KEY_INVALID",
    "message": "no API key on the request",
    "details": { "reason": "api_key_missing" }
  }
}

The other refusals work the same way. Their message texts and details.reason values are collected in the “Access errors” section.

05How to store a key

• Keep the key in your server’s environment variables or in a secret manager.
• Do not put the key in website code, mobile app code, a public repository, or logs. Send API requests from your server only.
• Give each integration its own key.
• If a key may have leaked, revoke it immediately and then create a new one.

FAQFrequently asked questions