Authentication
All PearMedica API requests require authentication via API keys. This guide covers key management, rate limiting, and security best practices.
API Key Format
PearMedica issues two types of API keys, distinguished by their prefix:
| Prefix | Environment | Usage |
|---|---|---|
| sk_live_ | Production | Live patient assessments. Usage is metered and billed. |
| sk_test_ | Development | Sandbox testing. Returns mock data, not billed. |
Using Your API Key
Include your API key in the Authorization header of every request:
Authorization: Bearer sk_live_your_api_key_hereSecurity Best Practices
- Never expose API keys in client-side code (browsers, mobile apps)
- Store keys in environment variables, not in source code
- Use
sk_test_keys for development and testing - Rotate keys immediately if you suspect they've been compromised
- Use separate keys for each environment (staging, production)
Key Management
Manage your API keys from the Dashboard → API Keys page. Available actions:
Create Key
Generate a new API key with a descriptive label. The full key is shown once — save it immediately.
Rotate Key
Generates a new key and invalidates the old one. Use POST /v1/keys/rotate or the dashboard.
Revoke Key
Permanently disables a key. All requests using it will receive 401 Unauthorized.
View Usage
See per-key usage metrics: total requests, last used timestamp, and rate limit status.
Rate Limiting
All API keys have a default rate limit of 100 requests per minute using a sliding window algorithm. Rate limit headers are included in every response:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709193600| Tier | Rate Limit | Monthly Quota |
|---|---|---|
| Pilot | 100 req/min | 200 assessments (free) |
| Professional | 100 req/min | 1,000 included + ₦20/additional |
| Enterprise | Custom | Custom — contact sales |
If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff to handle this gracefully.