Authentication & Authorization

PULSE authentication methods and API key management

Authentication & Authorization

PULSE uses API keys for authentication and authorization.

API Key Format

PULSE API keys follow this format:

pulse_prod_xxxxxxxxxxxxxxxxxxxxxxxx
       ├────┘ ├──────────────────────┘
       │      │
    environment  key material (32 characters)

• Prefix: pulse_prod_ (production) or pulse_dev_ (development)
• Length: Total 43 characters
• Characters: Alphanumeric + underscore

Creating API Keys

Via Dashboard

1. Log in to PULSE dashboard
2. Go to Settings → API Keys
3. Click “Create API Key”
4. Copy and store securely (only shown once)

Via API

curl -X POST https://api.example.com/api/v1/settings/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production_key"}'

Using API Keys

Include in Authorization header:

curl https://api.example.com/api/v1/stats \
  -H "Authorization: Bearer pulse_prod_xxxxx"

Or as query parameter:

curl "https://api.example.com/api/v1/stats?api_key=pulse_prod_xxxxx"

Key Rotation

Safely rotate API keys:

1. Generate new key
2. Update applications (gradual rollout)
3. Monitor old key usage
4. Revoke old key after 7 days

# Generate new key
curl -X POST https://api.example.com/api/v1/settings/keys \
  -H "Authorization: Bearer YOUR_OLD_KEY"

# Wait for applications to update...

# Revoke old key
curl -X DELETE https://api.example.com/api/v1/settings/keys/OLD_KEY_ID \
  -H "Authorization: Bearer YOUR_NEW_KEY"

Scopes

API keys have these scopes:

• events:write — Ingest events
• stats:read — Query analytics
• cohorts:read — Read cohorts
• cohorts:write — Create/modify cohorts
• admin — Full access

Rate Limiting

Each API key is rate limited:

Authorization: Bearer pulse_prod_xxxxx
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1703001294

Limits:

• Event ingestion: 10,000 events/minute
• API queries: 1,000 requests/minute
• Admin operations: 100 requests/minute

Security Best Practices

1. Store Securely

   • Use environment variables
   • Never commit to git
   • Use secrets manager

2. Rotate Regularly

   • Rotate every 90 days
   • On employee departure
   • If compromised

3. Use Minimal Scope

   • Only grant needed scopes
   • Create separate keys per service

4. Monitor Usage

   • Check last_used_at
   • Alert on unusual patterns
   • Revoke unused keys

Session Tokens

For session-based authentication:

# Create session
curl -X POST https://api.example.com/api/v1/session \
  -H "Content-Type: application/json" \
  -d '{"api_key": "pulse_prod_xxxxx"}'

# Use session
curl https://api.example.com/api/v1/stats \
  -H "Cookie: session=token_xxxxx"

Error Responses

Invalid API Key:

{
  "success": false,
  "error": "Invalid API key",
  "timestamp": 1703001234567
}

Rate Limited:

{
  "success": false,
  "error": "Rate limit exceeded. Retry after 60 seconds.",
  "timestamp": 1703001234567
}

Next Steps

• Event Ingestion — Send events
• API Keys Management — More API endpoints