Authentication

API keys, permissions, and security best practices

Overview

Appflow uses API keys for all authentication. Every request to the API must include a valid key in the Authorization header. Keys are scoped to projects, meaning a single key grants access to all apps within that project. Different key types provide different permission levels, so you can follow the principle of least privilege for each use case.

Authorization Header
Authorization: Bearer <API_KEY>

API Key Types

Appflow provides three key types, each designed for a specific environment. Choose the most restrictive key that satisfies your requirements.

Type
Prefix
Permissions
Use Case
Server Key
sk_
Full read/write
Backend services
Client Key
ck_
Write events only
Mobile SDKs
Read-Only Key
ro_
Read analytics
Dashboards, reports

Creating API Keys

You can create API keys from the dashboard under Settings → API Keys, or programmatically via the Management API. When creating a key, specify the key type and optionally limit it to specific scopes.

cURL
curl -X POST https://api-v2.appflow.ai/v1/api-keys \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "proj_xxx", "name": "Production iOS", "type": "client", "scopes": ["events:write"]}'

The response includes the full key value. This is the only time you will see the complete key, so store it securely. If you lose it, you will need to create a new one.

Creating API keys requires a Server Key (sk_). Client and Read-Only keys cannot create other keys.

Using API Keys

Include your API key in the Authorization header with the Bearer scheme on every request. All API endpoints require authentication.

cURL
curl https://api-v2.appflow.ai/v1/analytics/daily?app_id=app_xxx&days=7 \
  -H "Authorization: Bearer sk_xxx"

Requests with a missing, expired, or invalid key will receive a 401 Unauthorized response. Requests to endpoints outside the key's permission scope will receive a 403 Forbidden response.

401 Response
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  }
}

Security Best Practices

Follow these guidelines to keep your API keys and data secure.

Key Security Guidelines
Never expose server keys in client-side code. Server keys (sk_) have full read/write access and must only be used from your backend.
Use client keys in mobile SDKs. Client keys (ck_) can only write events, limiting the blast radius if compromised.
Rotate keys regularly. Create new keys and deprecate old ones on a schedule. Use the dashboard to revoke compromised keys immediately.
Use environment variables. Never hardcode keys in source code. Store them in your CI/CD secrets or a vault service.
Set key expiration dates. When creating keys via the API, set an expires_at field to automatically disable keys after a given period.

Rate Limits

API requests are subject to rate limits based on the endpoint category. Limits are applied per API key unless otherwise noted.

Endpoint Category
Limit
Event Ingestion
10,000 req/s per app
Analytics Queries
100 req/min per key
Management APIs
60 req/min per key
Webhook Delivery
Unlimited (server-to-server)

Handling Rate Limit Errors

When you exceed a rate limit, the API returns a 429 Too Many Requests response. The response includes a Retry-After header indicating how many seconds to wait before retrying.

429 Response Headers
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709856000
429 Response Body
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "retry_after": 12
  }
}
Implement exponential backoff in your clients. Start with the Retry-After value and double the wait time on each subsequent 429 response, up to a maximum of 60 seconds.