Letterby Docs

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_key

Create 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

LevelAllows
Read onlyEvery GET endpoint.
Full accessEverything: 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

StatusCodeCause
401missing_api_keyNo Authorization header, or it is not Bearer <key>.
401invalid_keyThe key is unknown or revoked, the team is suspended, or the person who created the key is no longer an owner or admin.
403insufficient_scopeA 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.

On this page