Authentication

All API requests require authentication via a Bearer token in the Authorization header. Unauthenticated requests will receive a 401 Unauthorized response.

API Key Format

API keys use the format sk_live_ followed by 40 random alphanumeric characters:

sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ab

Keys are bound to your user account. All screenshots created with a key are associated with your account's usage quota and billing plan.

Making Authenticated Requests

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

cURL

curl -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx" \
  https://screenshotrun.com/api/v1/screenshots

PHP (Laravel HTTP)

use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('SCREENSHOT_API_KEY'))
    ->get('https://screenshotrun.com/api/v1/screenshots');

PHP (Guzzle)

$client = new \GuzzleHttp\Client();

$response = $client->get('https://screenshotrun.com/api/v1/screenshots', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('SCREENSHOT_API_KEY'),
    ],
]);

Python (requests)

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['SCREENSHOT_API_KEY']}"}
response = requests.get("https://screenshotrun.com/api/v1/screenshots", headers=headers)

JavaScript (Node.js)

const response = await fetch("https://screenshotrun.com/api/v1/screenshots", {
  headers: {
    "Authorization": `Bearer ${process.env.SCREENSHOT_API_KEY}`,
  },
});

Ruby

require "net/http"
require "uri"

uri = URI("https://screenshotrun.com/api/v1/screenshots")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV['SCREENSHOT_API_KEY']}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

Go

req, _ := http.NewRequest("GET", "https://screenshotrun.com/api/v1/screenshots", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SCREENSHOT_API_KEY"))

resp, err := http.DefaultClient.Do(req)

Key Management

Manage your API keys from the API Keys page in your dashboard.

Creating keys

Click Create New Key and provide a descriptive name
Copy the key immediately — it is only shown once
Create separate keys for different environments (production, staging, development)

Managing keys

View all active keys and their last usage time
Optionally restrict keys to specific domains for added security
Revoke compromised keys immediately — revocation takes effect instantly

Domain restrictions

You can restrict an API key to only accept requests from specific domains. This is useful for client-side integrations where the key might be visible:

Add one or more allowed domains when creating or editing a key
Requests from unlisted domains will be rejected with 403 Forbidden
Domain restrictions are checked against the Origin and Referer headers

Security Best Practices

Practice	Description
Use environment variables	Store API keys in environment variables (`.env` files, secrets managers) rather than hardcoding them in source code
Never commit keys	Add `.env` to your `.gitignore`. Never commit API keys to version control
Rotate keys periodically	Create a new key, update your application, then revoke the old key. We recommend rotating keys every 90 days
Use domain restrictions	In production, restrict keys to your application's domains to prevent unauthorized usage
Separate keys per environment	Use different keys for development, staging, and production to limit the blast radius of a leaked key
Monitor usage	Regularly check your usage statistics for unexpected spikes that might indicate a compromised key

Authentication Errors

When authentication fails, you'll receive one of these responses:

Missing API key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is required. Include it in the Authorization header as 'Bearer YOUR_API_KEY'.",
    "status": 401
  }
}

Invalid API key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked.",
    "status": 401
  }
}

Domain not allowed

{
  "error": {
    "code": "DOMAIN_NOT_ALLOWED",
    "message": "This API key is not authorized for requests from this domain.",
    "status": 403
  }
}