​

API Best Practices

​

Authentication

• Use API keys (lk_live_...) for server-to-server integrations — never expose them in client-side code
• Store API keys in environment variables, not in source code
• Rotate keys regularly from Settings → Developer → API Keys
• Give each integration its own named key so you can revoke it independently

​

Workspace Resolution

When using an API key you do not need to pass x-workspace-id — the key already encodes the workspace. Only include the header if you want to explicitly validate which workspace you’re operating in. Passing an x-workspace-id that doesn’t match the key’s workspace returns a 401.

​

Error Handling

• Always check the HTTP status code before reading the response body
• For 403 errors, check whether the account has hit a plan limit or the API key lacks the required role
• For 409 (conflict), the short code or domain already exists — use a different value

​

Retries

• Retry 5xx errors and network timeouts with exponential backoff
• Do not retry 4xx errors — they indicate a problem with the request itself
• Add jitter to retry delays to avoid thundering-herd problems

​

Security

• Use HTTPS only — the API does not accept plain HTTP
• Never log raw API keys or JWT tokens
• Scope each key to the minimum required workspace and revoke unused keys