Authentication

Learn how to authenticate with the RenderDoc API using API keys for generating documents programmatically.

Overview

RenderDoc uses API keys for authentication when generating documents programmatically. API keys allow you to generate documents without exposing your account credentials.

info

Important: API keys are specifically designed for programmatic API access (server-to-server). Email/password authentication with JWT tokens is only used by the web dashboard - it should NOT be used for external API access.

API Keys

What are API Keys?

API keys are secure tokens that authenticate your application when making requests to the RenderDoc API. They act as a password for programmatic access.

Key Features:

Scoped Permissions: Limit what each key can do
Revocable: Disable a key without changing your password
Trackable: Monitor usage per key
Expirable: Set expiration dates for enhanced security

Creating an API Key

Via Dashboard (Recommended)

Navigate to Settings → API Keys in the dashboard
Click Create API Key
Configure the key:
- Name: Descriptive name (e.g., "Production Server", "Dev Environment")
- Permissions: Select what this key can do (generate documents, read templates, etc.)
- Expiration: Optional expiry date (recommended for security)
Click Create Key
IMPORTANT: Copy the key immediately - it won't be shown again

API Key Format: rd_sk_abc123xyz456def789...

Using API Keys

Authorization Header

Include your API key in the Authorization header with the Bearer scheme:

curl https://api.renderdoc.dev/api/v1/documents/generate \
  -H "Authorization: Bearer rd_sk_abc123xyz456..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "templateId": "tmpl_invoice",
    "format": "pdf",
    "variables": { "invoiceNumber": "INV-001", "customerName": "Acme Corp" }
  }'

JavaScript Example

const apiKey = 'rd_sk_abc123xyz456...';

const response = await fetch('https://api.renderdoc.dev/api/v1/documents/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    templateId: 'tmpl_invoice',
    format: 'pdf',
    variables: {
      invoiceNumber: 'INV-001',
      customerName: 'Acme Corp',
      total: 1500.00
    }
  })
});

const data = await response.json();
console.log('Document generated:', data.downloadUrl);

Python Example

import requests

api_key = 'rd_sk_abc123xyz456...'
url = 'https://api.renderdoc.dev/api/v1/documents/generate'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

payload = {
    'templateId': 'tmpl_invoice',
    'format': 'pdf',
    'variables': {
        'invoiceNumber': 'INV-001',
        'customerName': 'Acme Corp',
        'total': 1500.00
    }
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print('Document generated:', data['downloadUrl'])

What Can API Keys Access?

API keys provide access to document generation and related operations:

Available Endpoints

Endpoint	Description	Documentation
`POST /api/v1/documents/generate`	Generate single document	Generating Documents
`POST /api/v1/documents/generate/batch`	Generate batch of documents	Generating Documents
`GET /api/v1/documents/jobs/:id`	Get job status	Documents API
`GET /api/v1/templates`	List templates	Templates API

warning

Permissions: API keys have limited permissions for security. They can generate documents using existing templates but cannot:

Create or modify templates (dashboard only)
Access billing settings (dashboard only)
Manage team members (dashboard only)

This ensures that even if an API key is compromised, attackers cannot modify your templates or access sensitive data.

API Key Format

API keys use the format rd_sk_{random_string}:

Prefix: rd_sk_
Random String: Cryptographically secure identifier
Best Practice: Store securely, rotate regularly

Security Best Practices

1. Keep Keys Secret

✅ DO:

Store keys in environment variables
Use secret management services (AWS Secrets Manager, HashiCorp Vault)
Rotate keys regularly (every 90 days)

❌ DON'T:

Commit keys to version control
Hardcode keys in client-side code
Share keys via email or chat

2. Use Environment Variables

# .env file (add to .gitignore)
RENDERDOC_API_KEY=rd_sk_abc123xyz456...

// JavaScript
const apiKey = process.env.RENDERDOC_API_KEY;

# Python
import os
api_key = os.environ.get('RENDERDOC_API_KEY')

3. Limit Permissions

Grant the minimum permissions needed:

{
  "name": "Document Generator Service",
  "permissions": ["documents:generate"],
  "expiresAt": "2025-12-31T23:59:59Z"
}

4. Set Expiration Dates

Always set an expiration date for long-lived keys:

{
  "name": "Q4 Report Generator",
  "permissions": ["documents:generate"],
  "expiresAt": "2025-12-31T23:59:59Z"
}

5. Monitor Usage

Regularly review API key usage in the dashboard:

Check for unexpected activity
Monitor request volume
Review permission usage

6. Rotate Keys

Implement key rotation:

Create a new API key
Update your application with the new key
Test thoroughly
Delete the old key

Error Handling

Invalid API Key

Status Code: 401 Unauthorized

{
  "statusCode": 401,
  "code": "ERR_AKEY_002",
  "message": "Invalid API key",
  "timestamp": "2025-11-07T10:30:00.000Z",
  "path": "/api/v1/documents/generate"
}

Deactivated API Key

Status Code: 401 Unauthorized

{
  "statusCode": 401,
  "code": "ERR_AKEY_003",
  "message": "API key has been deactivated",
  "timestamp": "2025-11-07T10:30:00.000Z",
  "path": "/api/v1/documents/generate"
}

Insufficient Permissions

Status Code: 403 Forbidden

{
  "statusCode": 403,
  "code": "ERR_AUTH_005",
  "message": "You do not have permission to perform this action",
  "timestamp": "2025-11-07T10:30:00.000Z",
  "path": "/api/v1/templates/create",
  "relatedInfo": {
    "required": "templates:create",
    "granted": ["documents:generate"]
  }
}

Rate Limiting

API keys are subject to rate limits based on your plan:

Plan	Requests per Minute
Free	10
Starter	100
Growth	500
Scale	Custom

See Rate Limiting for details.

Managing API Keys

All API key management operations are performed through the dashboard at Settings → API Keys.

Available operations:

View all keys: See all active and expired keys
Create new key: Generate a new API key
View key details: Check creation date, last used, and expiration
Revoke key: Immediately disable a key
Set expiration: Add or update expiration date

info

Dashboard-Only: For security reasons, API key management is not available via API keys themselves. Use the dashboard to create, view, and revoke keys.

Common Questions

How many API keys can I create?

There's no limit on the number of API keys you can create. We recommend creating separate keys for each environment and service.

What happens if my key is compromised?

Immediately revoke the compromised key in the dashboard. Create a new key with different permissions and update your applications.

Can I use the same key in multiple environments?

While possible, it's not recommended. Use separate keys for development, staging, and production environments.

Do API keys expire automatically?

Only if you set an expiration date. Keys without an expiration date remain active until manually revoked.

Can I recover a deleted API key?

No, deleted keys cannot be recovered. You'll need to create a new key.

Overview​

API Keys​

What are API Keys?​

Creating an API Key​

Via Dashboard (Recommended)​

Using API Keys​

Authorization Header​

JavaScript Example​

Python Example​

What Can API Keys Access?​

Available Endpoints​

API Key Format​

Security Best Practices​

1. Keep Keys Secret​

2. Use Environment Variables​

3. Limit Permissions​

4. Set Expiration Dates​

5. Monitor Usage​

6. Rotate Keys​

Error Handling​

Invalid API Key​

Deactivated API Key​

Insufficient Permissions​

Rate Limiting​

Managing API Keys​

Common Questions​

How many API keys can I create?​

What happens if my key is compromised?​

Can I use the same key in multiple environments?​

Do API keys expire automatically?​

Can I recover a deleted API key?​