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.

      Your first API request

      Make this call before your first send. It touches nothing, costs nothing, and answers the two questions that cause most first-day confusion: is my key valid, and what is it allowed to do.

      curl https://api.lockally.com/v1/auth/whoami \
        -H "Authorization: Bearer $LOCKALLY_API_KEY"
      {
        "tenant": {
          "slug": "acme",
          "name": "Acme Ltd",
          "plan": "starter"
        },
        "scopes": ["send:write", "send:read"],
        "auth": "api_key",
        "key": {
          "id": "b1e4c0de-5a2f-4c7e-9d31-0a8f6b2c4d99",
          "label": "Production backend"
        }
      }

      What it tells you

      scopes is the list your key actually holds. Compare it against the scope the endpoint you are about to call requires, which is in the API Reference. Scopes cannot be added to a key after it is created, so a missing one means a new key, not an edit.

      tenant.plan matters because API access is checked on every request, not only when the key is made. A plan without API access stops every key at once, and restores them if you move back.

      auth is api_key here. It reads session when the call comes from a signed-in console session instead, and then there is no key object.

      key.label is the label you typed when creating it. If you are holding several keys, this is how you confirm you are using the one you think.

      If it fails

      401 Unauthorized. The key is missing, malformed, revoked, or presented as the wrong kind. A key issued as lk_test_ cannot be sent as lk_live_ or the reverse; authentication fails rather than quietly doing the wrong thing. Check you copied the whole key, including the prefix.

      Connection refused or a certificate error. Check the base URL. It is https://api.lockally.com, not app. (the console) or mail. (webmail).

      403 with the title Business mode required. Your key is fine. You have called an endpoint that needs hosted mailboxes from an API-only account. See Business, API and Both.

      Next

      Send something: Send your first email. Or read what comes back first: Understanding responses.