API keys

Every RenderScreenshot request is tied to your account by a key, and each key belongs to one workspace. The key's workspace decides which storage, webhook, logs and cache the request uses. This page explains the three key prefixes, how to create, rotate and revoke keys, and where to store them. It is part of the API documentation. If you only need your first request, start with the quick start.

Key types

All keys are a prefix followed by 32 letters and digits.

rs_pub_ and rs_secret_ keys come as a pair and belong together. Only an rs_live_ key authenticates an API call: send it as a Bearer token, or as the api_key query parameter for quick tests. An rs_pub_ or rs_secret_ value sent that way is rejected with HTTP 401, so the public key ID printed in signed URLs cannot be used to call the API. Signed URLs work only for GET /v1/screenshot.

How RenderScreenshot stores keys

For rs_live_ and rs_pub_ keys we store a SHA-256 hash and the last four characters, never the key itself. That is why a key is shown only once. After that, the dashboard shows it masked, for example rs_live_********************a1B2.

A secret key is the exception. To check a signature, the server must compute the same HMAC you did, so it needs the secret itself. rs_secret_ keys are therefore stored encrypted, not hashed. Treat a leaked secret key as seriously as a leaked live key.

Create a key

1. Open API Keys in the dashboard. Choose the workspace in the sidebar switcher first: the key is created in the workspace that is selected, and the page lists only that workspace's keys.
2. Select Create Key and give it a name that says where it will run, for example billing-worker production.
3. Copy the key from the confirmation. It is not shown again.
4. Store it as a secret in the environment that uses it.

Create a signing key pair

Signed URLs need an rs_pub_ public key ID and an rs_secret_ secret key that belong together. The publishable keys guide shows how to use the pair in frontend code.

1. Open API Keys in the dashboard and select Create Key.
2. Choose Signing key pair and give it a name, for example marketing site og:image.
3. Copy both values from the confirmation: the public key ID (rs_pub_) and the secret key (rs_secret_). Neither is shown again.
4. Store the secret key as a server-side secret, for example RS_SECRET_KEY. The public key ID can go in configuration, for example RS_PUBLIC_KEY_ID.

The list then shows the pair as two masked rows, Name (Public) and Name (Secret). Revoking either row revokes both keys, and every URL signed with the pair stops working. An account can have several pairs; each public key ID verifies only against the secret key created with it, and both keys of a pair are in the same workspace.

On a team account, owners and admins create and revoke keys and signing pairs (team roles). Members see the key list, masked, but cannot create or revoke keys. Keys belong to the account and its workspaces, not to people: removing a team member does not revoke or delete the keys that member created. Deleting a workspace deletes its keys, unless you move them first. See team roles.

An owner or admin can also move a key to another workspace with Move next to the key. The raw key does not change. The key then uses the new workspace's storage, webhook and cache, so the first renders after the move use credits again. A signing pair moves as one unit.

Rotate a key without downtime

A key does not expire, so rotate on a schedule, when a person with access leaves, and at once if a key may have leaked.

1. Create a new key with a name that includes the date.
2. Deploy it to every service that used the old key. Most platforms need a restart or redeploy to pick up a new secret.
3. On the API Keys page, watch the Last Used time of the old key. When it stops changing, nothing uses the old key any more.
4. Revoke the old key.

One key per service and environment makes step 3 easy to read and limits what one leak exposes.

Revoke a key

Select Revoke next to the key and confirm. Revocation is immediate and cannot be undone. The next request with that key fails with HTTP 401:

{
  "error": {
    "type": "authentication_error",
    "code": "missing_credentials",
    "message": "No valid API key or signature provided",
    "retryable": false,
    "docs": "https://renderscreenshot.com/docs/errors/missing-credentials"
  },
  "request_id": "c41d8e2a-5b7f-4a90-b3c6-2e8f1d0a9b57"
}

A missing, mistyped or revoked key all return this response today. Requests without a valid credential are also rate-limited per IP at 10 per minute, so a retry loop soon gets HTTP 429 as well. Do not retry a 401: it will not succeed until the key changes. Stop the job and alert someone. This Node.js check does that. It was tested on 2026-10-15 with renderscreenshot 1.1.0 against a local stub that returns the response above:

import { Client, TakeOptions, RenderScreenshotError } from 'renderscreenshot';

const client = new Client(process.env.RS_API_KEY);

try {
  await client.take(TakeOptions.url('https://example.com'));
} catch (err) {
  if (err instanceof RenderScreenshotError && err.httpStatus === 401) {
    // The key is missing, mistyped or revoked. Retrying cannot fix it:
    // stop the job and alert a human instead of burning through the queue.
    console.error('RenderScreenshot rejected RS_API_KEY. Rotate or restore the key.');
    process.exit(78); // EX_CONFIG
  }
  throw err;
}

Store keys safely

• Environment variables or a secret manager. Read RS_API_KEY at runtime. The SDKs and the CLI use that name.
• Never in Git. Add .env files to .gitignore. Scan for rs_(live|secret)_[A-Za-z0-9]{32} in CI.
• Never in frontend code or mobile apps. Anything shipped to a browser or device can be read. Use signed URLs for images the public loads.
• Avoid api_key in URLs outside tests. Query strings end up in server logs, proxy logs and browser history. The Bearer header does not.
• Separate keys per environment. A staging leak should not touch production credits.

The security best practices guide covers secret scanning and incident response in more depth.

Last verified 2026-10-18 against the API key model, the authentication code and the dashboard role checks.