Authentication
Authenticate with an API key in the Authorization header.
Send your API key as a bearer token on every request.
Authorization: Bearer lb_your_keyCreate a key
In Letterby open Settings, then Integrations. You need the owner or admin role.
Under API keys select Create key, name it and choose the access level.
Copy the key from the Copy your key dialog. Letterby stores only a hash, so it cannot be shown again.
Use one key per integration. To rotate, create a new key, deploy it, then select Revoke on the old one.
Access levels
| Level | Allows |
|---|---|
| Read only | Every GET endpoint. |
| Full access | Everything: reading, creating and updating offers, accepting and ending agreements, managing webhooks. |
A key always acts for the team it was created in and can only reach that team's data.
When a key lacks access, the error names the permission the endpoint needs, for example offers:write.
Errors
| Status | Code | Cause |
|---|---|---|
401 | missing_api_key | No Authorization header, or it is not Bearer <key>. |
401 | invalid_key | The key is unknown or revoked, the team is suspended, or the person who created the key is no longer an owner or admin. |
403 | insufficient_scope | A Read only key called an endpoint that writes. |
{
"error": {
"type": "authentication_error",
"code": "invalid_key",
"message": "The provided API key is invalid or has been revoked.",
"request_id": "req_5f2c9a1e7b3d4c6f8a0b1c2d3e4f5a6b",
"docs_url": "https://letterby.com/docs/api/errors#invalid_key"
}
}Keep keys safe
- Store keys in environment variables or a secrets manager, never in source code.
- Never use a key in a browser or mobile app.
- Revoke a key the moment it may have leaked. Revoking takes effect at once.
Next: Errors
The error format and every code.