Authentication

Choose an authentication method

API key authentication

An API key is a static bearer token you include in the Authorization header of every request. The SDK handles this automatically when you set CASEFORGE_API_KEY.

Generate an API key

1. Go to Dashboard → Settings → API Keys.
2. Select Create API key. Give the key a descriptive name (for example, local-dev-2026-03).
3. Choose a key type: Sandbox (prefix cf_sand_) for development, or Live (prefix cf_live_) for production data.
4. Copy the key immediately. The full key value is shown only once — if you close the dialog, you need to generate a new key.
5. Store the key in your environment: set CASEFORGE_API_KEY in your shell, .env file, or secrets manager.

Use the key in the SDK

import caseforge

# The SDK reads CASEFORGE_API_KEY from the environment automatically
client = caseforge.Client()

# To supply the key programmatically (e.g. from a vault)
client = caseforge.Client(api_key=get_secret("caseforge/api-key"))

import CaseForge from '@caseforge/sdk';

// Reads CASEFORGE_API_KEY from process.env automatically
const client = new CaseForge();

// Or supply it from your secrets provider
const apiKey = await getSecret('caseforge/api-key');
const client = new CaseForge({ apiKey });

curl https://api.caseforge.io/v2/cases \
  -H "Authorization: Bearer cf_sand_your_key_here"

OAuth 2.0 client credentials

For production integrations, use OAuth 2.0 client credentials. Your application exchanges a client ID and client secret for a short-lived access token. When the token expires, the SDK can automatically request a new one.

Register an application

1. Go to Dashboard → Settings → Applications.
2. Select Create application. Enter a name and description.
3. Under Grant types, select Client credentials.
4. Select the scopes your application needs. See the scopes reference below.
5. Save the application. The dashboard shows your client_id and client_secret. Store both in your secrets manager before closing the dialog.

Request an access token

The SDK handles token acquisition and renewal automatically. Configure it with your client credentials, and all subsequent API calls use a valid token:

import caseforge

# Configure client credentials — token management is automatic
client = caseforge.Client(
    client_id="app_8v3k9m",
    client_secret=get_secret("caseforge/client-secret"),
    scopes=["cases:read", "cases:write", "sar:write"],
)

# The SDK requests a token on first use and refreshes it before expiry
cases = client.cases.list(status="open")

import CaseForge from '@caseforge/sdk';

// Configure client credentials — token management is automatic
const client = new CaseForge({
  clientId:     'app_8v3k9m',
  clientSecret: await getSecret('caseforge/client-secret'),
  scopes:       ['cases:read', 'cases:write', 'sar:write'],
});

// Token is acquired on first use and renewed before expiry
const cases = await client.cases.list({ status: 'open' });

# Step 1: Acquire a token
curl -X POST https://auth.caseforge.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=app_8v3k9m&client_secret=YOUR_SECRET&scope=cases:read+cases:write"

# Response:
# {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,"scope":"cases:read cases:write"}

# Step 2: Use the token
curl https://api.caseforge.io/v2/cases \
  -H "Authorization: Bearer eyJ..."

Token lifecycle

Access tokens expire after 60 minutes. The SDK automatically requests a new token when the current one is within 5 minutes of expiry, so you don't need to handle token renewal in your application code.

Scopes reference

Request only the scopes your application needs. CaseForge follows the principle of least privilege — unused scopes increase your attack surface without providing value.

Security best practices

• Rotate API keys regularly. Treat API keys like passwords — rotate them on a schedule and immediately if you suspect compromise. Go to Dashboard → Settings → API Keys, revoke the old key, and replace it atomically in your environment.
• Scope client credentials narrowly. Create separate OAuth applications for separate services. An analytics pipeline should not hold sar:write scope.
• Use Sandbox keys for development. Sandbox keys (prefix cf_sand_) have no access to live data. They cannot trigger real SAR filings or affect production case queues.
• Log token acquisition events. Log when your application requests a new OAuth token. Unexpected spikes in token requests can indicate a bug or a compromised credential.
• Use HTTPS. The CaseForge API only accepts HTTPS. Plain HTTP requests return a connection error — they are not redirected.