Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      Permissions and least privilege

      A key carries a set of scopes, chosen when it is created and fixed for its lifetime. Every protected route checks for a specific scope, and a key without it gets 403 Insufficient scope naming the scope it wanted.

      The full list of twenty lives on the Authentication page. This page is about choosing among them.

      Scopes come in read and write pairs

      Almost every scope is thing:read or thing:write, and write does not imply read. A key that creates templates and also lists them needs both templates:write and templates:read.

      Three do not follow the pattern:

      Scope
      tenant:read Usage, health, storage and activity figures
      tenant:admin Team, billing and API keys. The most dangerous scope there is
      directory:sync, scim:provision Machine identities for an AD sync agent and an identity provider

      Least privilege in practice

      The useful question is not “what might this ever need” but “what breaks today if I leave this out”.

      What it does What it needs
      Sends transactional mail send:write
      Sends, and checks delivery send:write, send:read
      Sends from stored templates the above, plus templates:read
      Honours unsubscribes it manages itself plus suppressions:read, suppressions:write
      Receives webhooks only nothing. Webhooks are pushed to you; the scope is for managing subscriptions

      Most integrations are the first row. send:write alone is a genuinely common and correct answer.

      There is a real tension with keys being immutable: narrowing is safer, but widening later costs a full rotation. The resolution is to scope a key to the job the service does, not to the single endpoint it calls this week. A sending service gets the sending scopes. It does not get mailboxes:write because someone might add a feature.

      Scopes are not the only gate

      A scope can be necessary without being sufficient. Two other checks run:

      Account mode. Mailbox endpoints need hosted mailboxes, so on a Lockally API account they return 403 Business mode required whatever scopes the key carries. Granting mailboxes:read cannot unlock them, because there are no mailboxes to act on. The error carries "code": "business_mode_required" so you can tell it from a scope failure.

      Plan. API keys themselves are a plan feature, checked on every request, not just at creation.

      Per-mailbox grants

      inboxes:read and inboxes:write are not account-wide, and this catches people out. Holding the scope lets a key use the inbox endpoints at all; it does not say which mailboxes.

      Each mailbox is granted to a key one at a time:

      POST   /v1/api-keys/{keyID}/mailboxes     {"mailbox": "support@yourcompany.com"}
      GET    /v1/api-keys/{keyID}/mailboxes
      DELETE /v1/api-keys/{keyID}/mailboxes/{mailboxID}

      All three need tenant:admin.

      A mailbox with no grant answers 404, not 403. That is deliberate: a key should not be able to map which mailboxes exist by probing for a different status. The detail does not pretend otherwise:

      {
        "status": 404,
        "title": "Mailbox not found",
        "detail": "No such mailbox, or your key has no grant for it. Grants are managed via POST /v1/api-keys/{id}/mailboxes."
      }

      So a missing grant and a mistyped address are indistinguishable by status. Check the grant list before assuming the address is wrong.

      Grants apply to API keys only. An admin session reaches any mailbox on the account without them, which is why a key is the right credential for anything automated.

      A grant is refused for a mailbox with agent access disabled, or one holding an active end-to-end encryption key. In the second case the server genuinely cannot read the mailbox, so a grant would be a promise it could not keep.

      This is the strongest least-privilege tool here: a key for an assistant that answers support@ can be granted that one mailbox and reach nothing else, even though the scope is spelled the same as one that could reach many.

      What a key can never carry

      webmail is a real scope, and not grantable on an API key. It is minted by the server for a single mailbox session and pins a request to that mailbox. A tenant able to request it on a console key would hold something that looks mailbox-owner-scoped to every check that matters, which is the opposite of what those checks are for.

      Asking for it, or for any scope that is not one of the twenty, fails key creation with the full valid list in the error.