API Authentication

The API uses API keys for authentication. API keys provide secure, programmatic access to R4 platform features without requiring user credentials.

API Key Overview

An API key consists of two parts:

{accessKey}.{secret}

• Access Key: A public identifier used to look up the API key (e.g., rk_abc123def456)
• Secret: A private value that authenticates the request (e.g., ghijklmnopqrstuvwxyz1234567890abcdef)

The full API key looks like:

rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef

Generating an API Key

1. Log in to the R4 platform at https://r4.dev
2. Navigate to the tenant you want the API key to access
3. Navigate to Settings → API Keys
4. Click Create API Key
5. Enter a descriptive name for your key (e.g., "CI/CD Pipeline" or "Monitoring Script")
6. Click Generate
7. Important: Copy your API key immediately. The secret portion is only shown once and cannot be retrieved later.

Note: The API key will be scoped to the currently selected tenant. Make sure you're in the correct tenant before creating the key.

Using Your API Key

Recommended: X-API-Key Header

The preferred method is to pass your API key in the X-API-Key header:

curl -X GET "https://r4.dev/api/v1/machine/domain-manager/dns-records?domain=example.com" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

Alternative: Authorization Header

You can also use the Authorization header with the ApiKey scheme:

curl -X GET "https://r4.dev/api/v1/machine/domain-manager/dns-records?domain=example.com" \
  -H "Authorization: ApiKey rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

API Key Permissions

API keys have the following characteristics:

Understanding Tenant Scoping

When you create an API key, it is associated with:

1. A specific tenant - The key can only access resources within this tenant
2. The creating user - The key inherits the user's permissions within that tenant

This ensures fine-grained access control. For example, if you have multiple tenants (e.g., "Production" and "Development"), you can create separate API keys for each, limiting what automated systems can access.

Security Best Practices

1. Never Commit API Keys to Version Control

Add your API key to .gitignore and use environment variables:

# .gitignore
.env
.env.local

# .env
R4_API_KEY=rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef

2. Use Environment Variables

Store API keys in environment variables, not in code:

import os
 
API_KEY = os.environ.get("R4_API_KEY")

const API_KEY = process.env.R4_API_KEY

3. Rotate Keys Regularly

• Rotate API keys at least every 90 days
• Rotate immediately if you suspect a key has been compromised
• Use descriptive names to track which key is used where

4. Use Separate Keys for Different Environments

Create separate API keys for:

• Development/testing
• Staging
• Production

This allows you to rotate or revoke keys independently.

5. Monitor API Key Usage

Regularly review API key usage in the R4 dashboard:

• Check for unusual activity patterns
• Verify that all keys are still needed
• Remove keys that are no longer in use

Revoking an API Key

If an API key is compromised or no longer needed:

1. Log in to the R4 platform
2. Navigate to Settings → API Keys
3. Find the key you want to revoke
4. Click Archive to revoke the key

Archived keys are immediately invalidated and cannot be used for authentication.

Example Implementations

Python with Requests

import os
import requests
 
class R4Client:
    def __init__(self, api_key: str = None):
        self.api_key = api_key or os.environ.get("R4_API_KEY")
        self.base_url = "https://r4.dev/api/v1/machine"
 
    def _headers(self):
        return {"X-API-Key": self.api_key}
 
    def get_dns_records(self, domain: str):
        response = requests.get(
            f"{self.base_url}/domain-manager/dns-records",
            params={"domain": domain},
            headers=self._headers()
        )
        response.raise_for_status()
        return response.json()
 
# Usage
client = R4Client()
records = client.get_dns_records("example.com")

JavaScript/TypeScript with Fetch

class R4Client {
  private apiKey: string
  private baseUrl = 'https://r4.dev/api/v1/machine'
 
  constructor(apiKey?: string) {
    this.apiKey = apiKey || process.env.R4_API_KEY!
  }
 
  private headers() {
    return { 'X-API-Key': this.apiKey }
  }
 
  async getDnsRecords(domain: string) {
    const response = await fetch(
      `${this.baseUrl}/domain-manager/dns-records?domain=${encodeURIComponent(domain)}`,
      { headers: this.headers() },
    )
 
    if (!response.ok) {
      throw new Error(`API error: ${response.status}`)
    }
 
    return response.json()
  }
}
 
// Usage
const client = new R4Client()
const records = await client.getDnsRecords('example.com')

cURL

#!/bin/bash
 
# Set your API key (use environment variable in production)
export R4_API_KEY="rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"
 
# Get DNS records
curl -X GET "https://r4.dev/api/v1/machine/domain-manager/dns-records?domain=example.com" \
  -H "X-API-Key: $R4_API_KEY" \
  -H "Content-Type: application/json"

Troubleshooting

401 Unauthorized

If you receive a 401 error:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Check the following:

1. Header format: Ensure you're using X-API-Key (not X-Api-Key or x-api-key)
2. Key format: The key should be {accessKey}.{secret} with a period separator
3. Key status: Verify the key hasn't been archived in the dashboard
4. Typos: Double-check for copy/paste errors

403 Forbidden

If you receive a 403 error, the API key is valid but doesn't have access to the requested resource. This typically means the resource belongs to a different organization.

Need Help?

If you're having trouble with API authentication:

1. Check this guide's troubleshooting section
2. Verify your key in the R4 dashboard
3. Contact support if the issue persists