Authentication

The FORG API uses API keys for authentication. All requests must include a valid key in the Authorization header.

Creating an API key

1. Go to forg.pro/dashboard → Settings → API Keys
2. Click Create key
3. Choose a name, environment (live / test), and scope
4. Copy the key immediately — it is shown only once

API keys have the format forg_live_{32hex} for production and forg_test_{32hex} for the test environment.

Making authenticated requests

curl https://forg.pro/api/v1/sessions \
  -H "Authorization: Bearer forg_live_a3f9e2c1b84d7f6e0a2c1d8e9f0b3c4d"

// Node.js
const response = await fetch("https://forg.pro/api/v1/sessions", {
  headers: {
    "Authorization": `Bearer ${process.env.FORG_API_KEY}`,
    "Content-Type": "application/json",
  },
});
const data = await response.json();

Key scopes

Scopes are additive. A key with read:sessions and read:reports can do both but cannot write rules. Omit a scope to restrict it.

Test vs. live keys

Test keys (forg_test_...) operate against a sandbox environment where:

• Rules do not block real traffic
• Webhooks fire to a test endpoint that returns 200 for all events
• Budget counters reset every hour
• Data is purged after 7 days

Use test keys in CI pipelines, staging environments, and during initial setup. Live keys require Team plan or higher and operate against your production data.

Key rotation

To rotate a key without downtime:

1. Create a new key with the same scopes
2. Deploy the new key to your systems
3. Verify requests are succeeding with the new key
4. Revoke the old key in the dashboard

Revoking a key immediately invalidates it. Any in-flight requests using the old key will fail with 401.

Security best practices

• Store keys in environment variables, never in source code
• Use the minimum required scopes for each key
• Rotate keys every 90 days or after any suspected compromise
• Audit key usage in Settings → API Keys → Activity log
• Use test keys in non-production environments

Errors

// 401 - Missing or invalid key
{ "error": "Invalid API key", "code": "invalid_api_key", "status": 401 }

// 403 - Key lacks required scope
{ "error": "Insufficient scope: write:rules required", "code": "insufficient_scope", "status": 403 }