API Reference

API Keys

Create and manage API keys to authenticate your requests to the AlterLab API. Each key provides secure access to scraping endpoints.

Authentication Types

Method	Header	Use Case
API Key	`X-API-Key: sk_live_...`	Scraping endpoints, programmatic access
Session Token	`Authorization: Bearer ...`	Dashboard APIs, key management

Key Management Authentication

The API key management endpoints (list, create, delete) require session authentication from the dashboard, not API key authentication. This prevents API keys from being used to create more keys.

Key Format

AlterLab API keys follow a consistent format for easy identification:

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

sk_Secret key prefix (always present)

live_Environment indicator (production keys)

xxxx...32-character unique identifier

Key Security

API keys are shown only once at creation. Store them securely - you cannot retrieve the full key later. If lost, delete the key and create a new one.

API Reference

List API Keys

GET

/api/v1/api-keys

List all active API keys for the authenticated user. Returns key metadata without the actual key values.

Request Example

curl -X GET https://api.alterlab.io/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Response Example

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Key",
    "key_prefix": "sk_live_",
    "key": null,
    "scopes": ["read", "write"],
    "created_at": "2025-01-15T10:30:00Z",
    "last_used_at": "2025-01-15T14:22:15Z",
    "requests": 1250
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Development Key",
    "key_prefix": "sk_live_",
    "key": null,
    "scopes": ["read", "write"],
    "created_at": "2025-01-10T08:00:00Z",
    "last_used_at": null,
    "requests": 0
  }
]

Create API Key

POST

/api/v1/api-keys

Create a new API key. The full key is only returned once in this response - store it securely.

Parameters

Name	Type	Required	Description
name	`string`	Required	Display name for the key (must be unique per user)

Request Example

curl -X POST https://api.alterlab.io/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'

Response Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Key",
  "key_prefix": "sk_live_",
  "key": "sk_live_abc123def456ghi789jkl012mno345pq",
  "scopes": ["read", "write"],
  "created_at": "2025-01-15T10:30:00Z",
  "last_used_at": null,
  "requests": 0
}

Save Your Key!

The key field contains your full API key and is only returned during creation. Copy and store it immediately in a secure location like a password manager or secrets vault.

Delete API Key

DELETE

/api/v1/api-keys/{key_id}

Revoke an API key. The key is soft-deleted and can no longer be used for authentication.

Parameters

Name	Type	Required	Description
key_id	`uuid`	Required	The UUID of the API key to delete

Request Example

curl -X DELETE https://api.alterlab.io/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Response Example

// 204 No Content on success

Using API Keys

Once you have an API key, use it to authenticate requests to scraping endpoints:

import requests

API_KEY = "sk_live_your_key_here"

response = requests.post(
    "https://api.alterlab.io/api/v1/scrape",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "url": "https://example.com",
        "mode": "light"
    }
)

print(response.json())

Best Practices

1. Use Environment Variables

Never hardcode API keys in your source code. Use environment variables instead.

# .env file
ALTERLAB_API_KEY=sk_live_your_key_here

# Python
import os
api_key = os.environ.get("ALTERLAB_API_KEY")

2. Use Separate Keys for Environments

Create separate API keys for development, staging, and production. This allows you to revoke a compromised key without affecting other environments.

3. Rotate Keys Periodically

Rotate your API keys every few months as a security best practice. Create a new key, update your applications, then delete the old key.

4. Monitor Usage

Check the requests count and last_used_at timestamp to identify unused keys that should be deleted.

5. Never Share Keys

Each team member or service should have their own API key. This provides better audit trails and allows individual revocation if needed.

Common Errors

Status	Error	Cause
`401`	Unauthorized	Missing or invalid session token
`404`	Key not found	Key ID doesn't exist or already deleted
`409`	Conflict	Key with that name already exists

← REST API Reference Webhooks Guide →