Skip to main content

​
Overview

Proliferate uses two different authentication patterns depending on the endpoint:
  1. API Key in Payload - For SDK data ingestion (errors, logs, replays)
  2. Bearer Token in Header - For source map uploads and dashboard API access

​
API Key in Payload

Used by SDKs to ingest data (errors, logs, session replays). The API key is included in the request body.

​
Format

API keys follow the pattern: pk_<random_string> Example: pk_abc123def456ghi789

​
Usage

POST /api/v1/errors

{
  "api_key": "pk_abc123def456ghi789",
  "event_id": "evt_xyz789",
  "timestamp": "2025-01-15T10:30:00Z",
  "type": "exception",
  "exception": {
    "type": "TypeError",
    "message": "Cannot read property 'foo' of undefined",
    "stack": "..."
  }
}

​
Why in Payload?

Including the API key in the payload allows SDKs to send data via sendBeacon in browsers, which has restrictions on custom headers. This ensures reliable delivery even when the page is unloading.

​
Security Considerations

  • HTTPS Only: Always use HTTPS in production to protect API keys
  • No Client-Side Exposure: API keys are exposed in client-side code (browser, mobile apps) - this is expected and safe for ingestion-only operations
  • Key Rotation: Rotate keys if you suspect compromise
  • Separate Keys per Environment: Use different keys for development, staging, and production

​
Bearer Token in Header

Used for source map uploads, release management, and dashboard API access. The API key is passed in the Authorization header.

​
Format

Authorization: Bearer pk_abc123def456ghi789

​
Usage

curl -X POST https://api.proliferate.com/api/v1/sourcemaps \
  -H "Authorization: Bearer pk_abc123def456ghi789" \
  -F "release=v1.2.3" \
  -F "url=~/static/js/main.js" \
  -F "sourcemap=@dist/main.js.map"

​
Why in Header?

Bearer tokens in headers are the standard for API authentication and work well for:
  • Build tool integrations (webpack, vite, etc.)
  • CI/CD pipelines
  • Server-to-server communication

​
Security Considerations

  • Keep Keys Secret: Never commit API keys to version control
  • Use Environment Variables: Store keys in CI/CD secrets or environment variables
  • Limit Exposure: Only use Bearer authentication in server-side or build-time contexts

​
Session-Based Authentication (Dashboard)

For dashboard API access (listing projects, viewing issues, etc.), use session-based authentication with cookies.

​
Getting a Session

Users authenticate via WorkOS OAuth:
1

User Logs In

User visits /login and is redirected to WorkOS
2

WorkOS Callback

After authentication, WorkOS redirects to /api/v1/auth/callback
3

Session Created

Backend sets secure, HTTP-only cookies
4

Access Dashboard API

All dashboard API calls include session cookies automatically

​
Usage

// Get current user's organizations
const response = await fetch('/api/v1/organizations', {
  credentials: 'include', // Include cookies
});

// Get project details
const project = await fetch('/api/v1/projects/123', {
  credentials: 'include',
});
Session cookies are automatically included by the browser. No manual authentication needed.

​
Getting API Keys

​
Via Dashboard

1

Navigate to Project Settings

Go to your project in the dashboard
2

API Keys Section

Click on “API Keys” in the sidebar
3

Create New Key

Click “Create API Key” and give it a descriptive name
4

Copy Key

Copy the key immediately - it’s only shown once!

​
Via API

Create an API key programmatically: 
curl -X POST https://api.proliferate.com/api/v1/projects/{project_id}/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'
The full API key is only returned once during creation. Store it securely!

​
Error Responses

​
401 Unauthorized

Invalid, missing, or revoked API key: 
{
  "detail": "Invalid API key"
}
Common causes:
  • API key not provided
  • API key format incorrect
  • API key has been revoked
  • API key doesn’t exist

​
403 Forbidden

Valid API key but insufficient permissions: 
{
  "detail": "You do not have access to this project"
}
Common causes:
  • API key belongs to a different project
  • User doesn’t have access to the organization

​
Best Practices

​
Environment-Specific Keys

Use different API keys for each environment:
.env.production
PROLIFERATE_API_KEY=pk_prod_abc123...
.env.staging
PROLIFERATE_API_KEY=pk_staging_def456...
.env.development
PROLIFERATE_API_KEY=pk_dev_ghi789...

​
Naming Conventions

Use descriptive names when creating keys:
  • Production Web App
  • Staging API Server
  • Development - John's Machine
  • CI/CD Pipeline
This makes it easy to identify and revoke keys when needed.

​
Rotation Strategy

Rotate API keys periodically or when:
  • A team member with access leaves
  • A key may have been exposed (committed to git, shared in chat, etc.)
  • As part of regular security hygiene (every 90-180 days)
To rotate:
  1. Create a new API key
  2. Update your application/CI with the new key
  3. Deploy the change
  4. Revoke the old key

​
Storage

DO:
  • Store keys in environment variables
  • Use secret management services (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Use CI/CD platform secret storage (GitHub Secrets, GitLab CI Variables, etc.)
DON’T:
  • Commit keys to version control
  • Share keys in chat or email
  • Store keys in plain text files
  • Hardcode keys in source code

​
Monitoring

Track API key usage:
  • Check last_used_at timestamp in the API keys list
  • Revoke unused keys to reduce attack surface
  • Set up alerts for unusual usage patterns

​
Rate Limits

Current rate limits:
  • Error ingestion: 1000 events/second per project
  • Log ingestion: 5000 logs/second per project
  • Source map uploads: 100 uploads/hour per project
  • Dashboard API: 1000 requests/hour per user
Rate limits are subject to change. Contact support if you need higher limits for production use.