API authentication

What this guide covers#

Authenticate API requests with a server-side key. Keep API keys out of browsers, mobile apps, and client-side bundles.

Use the API when your own product, backend, website form, mobile app, or internal system should create a Letterbook conversation.

Setup steps#

1. Create an API key in Letterbook.
2. Store the key in a server-side environment variable or secret manager.
3. Send authenticated requests from your server.
4. Add logging for request IDs and error responses.
5. Rotate keys on a regular schedule.
6. Revoke keys immediately if they are exposed.

Example request#

curl https://api.letterbook.ai/api/example \
  -H "Authorization: Bearer LETTERBOOK_API_KEY"

Where API keys belong#

API keys should only live in trusted server-side environments:

• Backend services
• Serverless functions
• Secure job workers
• Secret managers used by your infrastructure

Do not put Letterbook API keys in:

• Browser JavaScript
• Mobile apps
• Public repositories
• Static site environment variables exposed to the client
• Customer-controlled automation tools

For browser forms and mobile apps, send the request to your own backend first. Your backend can validate the input, attach trusted metadata, and call Letterbook with the server-side key.

Error handling#

Treat API failures like support intake failures. If a ticket cannot be created, your product should either retry safely or show the customer a clear fallback.

Recommended behavior:

• Use timeouts so a support form does not hang forever.
• Retry transient errors with backoff.
• Avoid retrying invalid requests until the payload is fixed.
• Log the customer identifier and your internal request ID.
• Alert your team if ticket creation repeatedly fails.

Rotation and revocation#

Rotate keys when teammates leave, when infrastructure changes, or when a key may have been exposed. Keep old and new keys separate during rollout so you can verify the new key before removing the old one.