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.

      Creating and managing keys

      In the console

      1. Open app.lockally.com/api-keys
      2. Create key
      3. Give it a label, for example production-backend
      4. Choose the scopes it needs
      5. Copy the key. It is shown once.

      The label is free text and is the only way you will tell keys apart later, so name it after the thing that holds it rather than after what it does.

      Over the API

      POST /v1/api-keys

      Required scope: tenant:admin

      {
        "label": "production-backend",
        "scopes": ["send:write", "send:read"],
        "test": false
      }

      Both label and scopes are required, and scopes must have at least one entry. A scope the API does not enforce is rejected, and the error lists every bad one at once along with the full valid set, so you do not discover them one request at a time.

      The response is the only time you see the secret

      {
        "id": "8c1d4f2a-6b3e-4d19-9a27-5e0f1c8b7a44",
        "tenant_id": "4f1e7b90-2c83-4a61-9d55-7e2a0b4c6d18",
        "prefix": "k3m9x2pq",
        "label": "production-backend",
        "scopes": ["send:write", "send:read"],
        "test": false,
        "created_at": "2026-10-17T09:12:44Z",
        "secret": "lk_live_k3m9x2pq_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
      }

      Anatomy of a key

      lk_live_k3m9x2pq_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
      └──┬───┘└───┬──┘ └───────────────┬──────────────┘
         │        │                    │
         │        │                    └─ 32-char secret, hashed at rest
         │        └─ 8-char prefix, stored in the clear, identifies the row
         └─ environment: lk_live_ or lk_test_

      The prefix is safe to log and safe to quote in a support ticket. It is how you and we both refer to a key without handling the secret. The console shows it on every key.

      Listing your keys

      GET /v1/api-keys

      Returns every key on the account, revoked ones included, with id, prefix, label, scopes, test, created_at, revoked_at and last_used_at. Never a secret.

      last_used_at is the useful field. It is how you find keys nothing is using any more, which are the ones worth revoking. It is updated off the request path, so it is accurate to within moments rather than exactly.

      What you can and cannot change

      PATCH /v1/api-keys/{id} edits a key in place, without reissuing its secret.

      Scopes Editable. Replaced wholesale, not merged
      Label Editable
      Expiry Editable, including removing one
      Live or test Fixed, and cannot be converted
      The secret Never changes. To change it, rotate

      Absent means unchanged, so renaming a key does not disturb its expiry. For expires_at there are three different requests, and the difference matters: omit the field to leave the expiry alone, send a timestamp to set one, and send an explicit null to remove one.

      # Narrow a key's scopes and give it a deadline, in one call.
      curl -X PATCH https://api.lockally.com/v1/api-keys/$KEY_ID \
        -H "Authorization: Bearer $LOCKALLY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"scopes":["send:write"],"expires_at":"2027-01-31T00:00:00Z"}'

      Expiry

      A key with no expires_at never expires, which is how every key behaved before expiry existed and how every key created without the field still behaves. Nothing was given a deadline retroactively.

      Expiry is enforced at authentication, not by a background sweep, so a key fails the first request after its deadline rather than at some point afterwards. The holder of the real secret is told the key expired and when; anybody presenting a wrong secret gets the ordinary indistinguishable 401, because telling them would confirm the prefix.

      You get warned twice

      The account’s alert address receives a notice 14 days and 3 days before a key expires, naming the label and the prefix. Fourteen days is time to schedule a rotation; three days is the one that gets read.

      One notice per threshold, and never two at once: a key already inside three days gets the three-day notice only, not that one plus “expires in 14 days” about the same key.

      Two things reset or suppress them, and both are what you would want:

      • Changing a key’s expiry warns again about the new deadline. Extending a deadline does not quietly buy the key another life with nobody told.
      • Rotating a key sends nothing for the overlap window. You set that deliberately and the console already showed you when it ends.

      These honour the account’s security-notification preference, the same one the key-created notice uses.

      Rotation

      POST /v1/api-keys/{id}/rotate issues a successor and puts a short expiry on the key you rotated, so both work until the overlap ends. That window is the whole feature: without it, rotation is revocation with extra steps and every caller has to swap credentials in the same instant.

      curl -X POST https://api.lockally.com/v1/api-keys/$KEY_ID/rotate \
        -H "Authorization: Bearer $LOCKALLY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"grace_seconds":3600}'

      The successor inherits the scopes, the label and the test flag. The label is kept on purpose: it names the integration, and the integration has not changed. Tell them apart by created_at, and by rotated_to on the predecessor.

      grace_seconds defaults to 24 hours and is capped at 30 days. The response’s expires_at is the predecessor’s deadline, so the rotation itself tells you how long you have to cut over.

      A key that has already been rotated cannot be rotated again. Chaining overlaps would leave several live keys for one integration, which is the opposite of the point; rotate the successor instead.

      Creating a key emails the account owner

      A new key triggers a security notification to the account’s alert address, carrying the label, the prefix, the scopes, the creating IP and the time. Never the secret.

      It honours the account’s security-notification preference, which is on by default and can be turned off in the console. If you are automating key creation, expect the mail.

      Keys need a plan that includes them

      The plan is checked on every request, not only at creation. An account that moves to a plan without API access finds its existing keys stop working at once, and start working again if it moves back, with nothing to reissue.