Getting Started

Authentication

Every SDK request is authenticated using an API key pair (clientId + secret). Keys are scoped to a specific project and environment.

API Key Pair

Each API key consists of two parts:

Field	Format	Description
clientId	`pk_live_xxx`	Public identifier. Safe to embed in client-side code.
secret	`sk_live_xxx`	Private secret. Keep server-side only when possible.

The SDK supports two authentication methods. Both are handled automatically by the SDK — you just provide credentials during initialization.

Combines both credentials into a single Authorization header.

http

Authorization: Bearer <clientId>:<secret>

# Example:
Authorization: Bearer pk_live_abc123:sk_live_xyz789

Pass credentials as two individual headers. Useful for proxies or API gateways.

http

X-Client-ID: pk_live_abc123
X-Client-Secret: sk_live_xyz789

API keys are scoped to control what the SDK can access. Scopes are configured when creating the key in the dashboard.

Scope	Grants Access To
`flags:read`	Fetch flag definitions and evaluate flags
`configs:read`	Fetch remote configuration values
`logs:write`	Ingest log events and error reports
`admin`	Full access (all scopes). Use with caution.

Every API key is subject to rate limiting. The SDK handles rate-limit responses automatically by using locally cached data.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only on 429)

Origin Allow-List

Restrict which domains can use this API key. Requests from unlisted origins receive a 403.

IP Allow-List

Restrict which IP addresses can use this API key. Ideal for server-side SDKs.

Key Revocation

Instantly revoke a key from the dashboard. Revoked keys return 410 Gone.

Audit Trail

Every key validation is logged. Track which keys are used and from where.