API keys

An API key lets a program of yours call the Little Worker API as you. This page shows how to make a key, how to send it, what the Can allow actions switch opens, and what stops a key.

What a key is

A key is a secret that starts with lw_key_. It acts as the person who made it, in that person's workspace, so a program that holds it can give your workers tasks and read their work. It opens only the API at https://core.thelittleworker.com/api/v1. It never opens the app's own routes.

Anyone who holds a key can use your workers. Keep it in your program's secrets, never in code, and never save it as a password a worker can read.

1Step 1: Make a key

Sign in at app.thelittleworker.com, open Settings, then API Keys, and choose Create Key.

1. In New API Key, give the key a Name, up to 80 characters. Name it after the program that will use it.
2. Choose whether to turn on Can allow actions. It is off to begin with. The next section says what it opens.
3. Choose Create. Copy Your Key shows the key. Copy it, then choose Done.

The key is shown once. Little Worker keeps only a fingerprint of it and its last four characters, so it cannot show the key again. If you lose a key, remove it and make a new one.

Settings lists the keys you made, each with its name, the last four characters, the day it was made and the day it was last used. Remove a key there when a program no longer needs it.

2Step 2: Send it with every request

Send the key in the x-api-key header. Every request also needs the Little-Worker-Version header. This call lists your workers:

curl https://core.thelittleworker.com/api/v1/workers \
  -H "x-api-key: $LITTLE_WORKER_API_KEY" \
  -H "Little-Worker-Version: 2026-10-19"

const response = await fetch("https://core.thelittleworker.com/api/v1/workers", {
  headers: {
    "x-api-key": process.env.LITTLE_WORKER_API_KEY ?? "",
    "Little-Worker-Version": "2026-10-19",
  },
})
console.log(response.status, await response.json())

import os

import requests

response = requests.get(
    "https://core.thelittleworker.com/api/v1/workers",
    headers={
        "x-api-key": os.environ["LITTLE_WORKER_API_KEY"],
        "Little-Worker-Version": "2026-10-19",
    },
)
print(response.status_code, response.json())

The answer is 200. data lists your workers, newest first, and next_page is null when there are no more:

{
  "data": [
    {
      "type": "worker",
      "id": "worker_bf5ff997fca044b38dc1cc9ea5b60100",
      "version": 1,
      "name": "Copywriter",
      "status": "active"
    }
  ],
  "next_page": null
}

A client that cannot set x-api-key may send Authorization: Bearer lw_key_... instead. If a request carries both, x-api-key is the one used.

If the request is refused, error.type and details.error_code say why:

A bad key is answered before the version is checked, so a request with both problems gets 401. Here is the 401 body for a key that is not valid:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "This API key is not valid. Make a new one.",
    "retryable": false,
    "details": { "error_code": "unauthenticated" }
  },
  "request_id": "request_3f2a9c1d7e5b4a8f9d0c2e4b6a8d1f3c"
}

A 401 also carries a WWW-Authenticate header that names a document about how to get a key. An agent that cannot make a key itself can read how to ask a person for one.

What Can allow actions opens

Some calls decide for a person: they let a worker act without asking, or they answer a worker that asked. A key made with Can allow actions off cannot make them. With it on, a key can:

• Answer a worker's approvals with user.approval events, to allow or deny an action. Approvals says who may answer, and Answer approvals from your program shows how.
• Make a worker's networking unrestricted, so the worker can reach any website. Without the switch the answer is 403 with person_required.
• Set a password's permission to always, so a worker uses the password without asking. Without the switch the answer is 403 with person_required.

Turn it on for a program that applies a rule you wrote, and leave it off for the rest.

Even with the switch on, a key never answers these. Only a person can, in the app, and a key that tries gets 403 with person_required:

• A worker's first use of a saved password.
• An email a worker sends.
• A press on a risky control in the worker's browser.
• A public post, such as publishing on X.
• A payment, and any other step that is a card in the app.
• A refund.

A key can also be made to delete tasks, with Can delete tasks. Settings does not offer that switch yet, so a key made there cannot delete a task. Archive a task instead.

How many keys

A workspace holds up to 20 keys. When you have 20, Settings says to remove one before it makes another.

The limits on requests are not per key. All of a workspace's keys share one count of 1,200 reads and 300 writes a minute, and 10 open event streams. Past a limit the answer is 429, with Retry-After in seconds.

What stops a key

A key works until one of these happens:

• You remove it. Choose Remove next to the key in Settings. Programs that use it stop working right away. A task the program already started goes on, so stop it too if it should not.
• Its owner leaves the workspace. The key stops at once.
• The owner's account is deleted, or the workspace is deleted. The key stops at once.

After any of these, a request with the key is answered 401. A key does not expire by itself.

Next steps

• Quickstart: make a worker, give it a task, and read the result.
• Answer approvals from your program: use a key made with Can allow actions.
• Overview: the headers, errors and limits every request meets.
• Stop work and keep history: stop what a program started before you remove its key.