PackagesAuth
API Keys
Generate secure API keys for programmatic access to your application. Supports both authenticated and anonymous key creation for flexible developer onboarding.
Quick Start
Create an API key without authentication:
curl -X POST https://api.example.com/api/v1/auth/api-key \
-H "Content-Type: application/json" \
-d '{"anonymous": true, "email": "developer@example.com"}'Overview
API keys provide a way for developers and applications to authenticate with your API without using session-based authentication. They're ideal for:
- Third-party integrations — Allow external services to access your API
- Developer onboarding — Let developers get started quickly without signing up
- CI/CD pipelines — Authenticate automated deployments and scripts
- Mobile apps — Authenticate native applications
- Webhooks — Verify incoming webhook requests
Anonymous API Key Creation
The OneApp API supports anonymous API key creation, allowing developers to get started immediately without creating an account. This is controlled by a feature flag and can be disabled in production if needed.
How it works
- Developer sends a POST request with
anonymous: true - API validates the feature flag is enabled
- API key is created with limited scopes (read-only by default)
- Developer receives the API key immediately
Request
POST /api/v1/auth/api-key
Content-Type: application/json
{
"anonymous": true,
"email": "developer@example.com", // optional, for identification
"name": "My Development Key", // optional, auto-generated if omitted
"expiresInDays": 30, // optional, default 30 days
"scopes": ["read"] // optional, default ["read"]
}Response
{
"apiKey": "sk_live_abc123...",
"id": "key_xyz789",
"name": "My Development Key",
"expiresAt": "2025-01-22T00:00:00.000Z"
}Code Examples
JavaScript/TypeScript
async function getAnonymousApiKey(email?: string) {
const response = await fetch("https://api.example.com/api/v1/auth/api-key", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
anonymous: true,
email,
name: "My App API Key",
expiresInDays: 30
})
});
if (!response.ok) {
throw new Error("Failed to create API key");
}
const { apiKey, id, expiresAt } = await response.json();
// Store the API key securely
console.log("API Key created:", id);
console.log("Expires:", expiresAt);
return apiKey;
}
// Usage
const apiKey = await getAnonymousApiKey("developer@example.com");Python
import requests
def get_anonymous_api_key(email: str = None) -> str:
response = requests.post(
'https://api.example.com/api/v1/auth/api-key',
json={
'anonymous': True,
'email': email,
'name': 'Python SDK Key',
'expiresInDays': 30,
}
)
response.raise_for_status()
data = response.json()
return data['apiKey']
# Usage
api_key = get_anonymous_api_key('developer@example.com')cURL
# Create an anonymous API key
curl -X POST https://api.example.com/api/v1/auth/api-key \
-H "Content-Type: application/json" \
-d '{
"anonymous": true,
"email": "developer@example.com",
"name": "CLI Tool Key"
}'
# Use the API key in subsequent requests
curl https://api.example.com/api/v1/data \
-H "Authorization: Bearer sk_live_abc123..."Authenticated API Key Creation
When a user is logged in, they can create API keys associated with their account. These keys inherit the user's permissions and can be managed through the dashboard.
Request
POST /api/v1/auth/api-key
Authorization: Bearer <session_token>
Content-Type: application/json
{
"name": "Production API Key",
"expiresAt": "2025-12-31T23:59:59.000Z",
"scopes": ["read", "write", "admin"]
}Response
{
"id": "key_abc123",
"name": "Production API Key",
"key": "sk_live_...",
"expiresAt": "2025-12-31T23:59:59.000Z",
"scopes": ["read", "write", "admin"],
"createdAt": "2025-01-01T00:00:00.000Z"
}Managing API Keys
List API Keys
Retrieve all API keys for the authenticated user.
GET /api/v1/auth/api-key
Authorization: Bearer <session_token>Get API Key Details
GET /api/v1/auth/api-key/:id
Authorization: Bearer <session_token>Update API Key
PUT /api/v1/auth/api-key/:id
Authorization: Bearer <session_token>
Content-Type: application/json
{
"name": "Updated Key Name",
"scopes": ["read", "write"]
}Delete/Revoke API Key
DELETE /api/v1/auth/api-key/:id
Authorization: Bearer <session_token>Using API Keys
Once you have an API key, include it in the Authorization header of your requests:
curl https://api.example.com/api/v1/resource \
-H "Authorization: Bearer sk_live_abc123..."Or use it as a query parameter (not recommended for sensitive operations):
curl "https://api.example.com/api/v1/resource?api_key=sk_live_abc123..."Security Best Practices
Do's
- Store keys securely — Use environment variables or secret management services
- Use appropriate scopes — Only request the permissions you need
- Rotate keys regularly — Set expiration dates and rotate keys periodically
- Monitor usage — Check API key analytics for unusual activity
- Use HTTPS — Always transmit API keys over encrypted connections
Don'ts
- Don't commit keys to git — Add them to
.gitignore - Don't share keys — Each developer/service should have their own key
- Don't use in client-side code — API keys in browser JavaScript are visible to users
- Don't log API keys — Ensure your logging doesn't capture sensitive headers
Feature Flag Configuration
Anonymous API key creation is controlled by the auth-anonymous-api-key feature flag. To disable it:
export const authAnonymousApiKeyFlag = flag({
key: "auth-anonymous-api-key",
decide: () => false // Set to false to disable
});Or configure it via Edge Config for runtime control without redeployment.
Rate Limits
API key creation is rate-limited to prevent abuse:
| Operation | Limit |
|---|---|
| Anonymous key creation | 5 per hour per IP |
| Authenticated key creation | 10 per hour per user |
| Key validation | 100 per minute per key |
Error Handling
Common Errors
| Status | Error | Description |
|---|---|---|
| 400 | Invalid request | Missing or invalid parameters |
| 401 | Authentication required | Anonymous creation disabled and no session |
| 403 | Anonymous API key creation is not enabled | Feature flag is disabled |
| 429 | Rate limit exceeded | Too many requests |
Error Response Format
{
"error": "Anonymous API key creation is not enabled",
"statusCode": 403
}Next Steps
- Authentication Overview — Learn about all auth methods
- Security Best Practices — Secure your application
- OneApp API — API server documentation