---
title: "API Keys and Authentication | Leadsets Docs"
description: "Authenticate Leadsets REST and MCP calls with an ls_live_ Bearer key. Access levels, expiry, rotating and revoking keys, and every 401 and 403 message."
canonical: https://www.leadsets.ai/docs/authentication
updated: 2026-11-11
---

Get started / Authentication

# Authentication.

Every call to the REST API and the MCP server sends an API key as a Bearer token. Keys belong to your workspace, carry an access level, and can expire or be revoked at any time.

## Send your key

Put the key in the `Authorization` header. The same key works for REST at `https://api.leadsets.ai/v1` and for MCP at `https://mcp.leadsets.ai`.

```bash
curl https://api.leadsets.ai/v1/usage \
 -H "Authorization: Bearer $LEADSETS_KEY"
```

```ts
import { Leadsets } from "@leadsetsai/sdk";

const ls = new Leadsets(process.env.LEADSETS_KEY);
const usage = await ls.usage.get();
```

```python
import os
from leadsets import Leadsets

ls = Leadsets(os.environ["LEADSETS_KEY"])
usage = ls.usage.get()
```

Keys start with `ls_live_`. Keep them server-side, in an environment variable or a secret manager. Never put a key in a browser, a mobile app or a public repository.

MCP clients send the same header. In Claude Code:

```
claude mcp add --transport http leadsets https://mcp.leadsets.ai \
 --header "Authorization: Bearer $LEADSETS_KEY"
```

Other clients are in [Connect via MCP](https://www.leadsets.ai/docs/mcp).

## Create a key

1. Open [API keys](https://www.leadsets.ai/app/keys) in the dashboard and click **New key**.
2. Name it after where it will run, for example "n8n production".
3. Pick an access level and an expiry: never, 30, 90 or 365 days.
4. Copy the key. It is shown once. Leadsets keeps only a hash, so a lost key can be replaced but not recovered.

## Access levels

Each key has one access level. Pick the smallest one that does the job.

| Level | Can call | Who can create it |
| --- | --- | --- |
| full | **Full access.** Every tool and `GET /v1/usage`. | Owners and admins |
| data | **Search + enrich.** Every tool and `GET /v1/usage`. | Anyone in the workspace |
| read | **Read only.** `GET /v1/usage` and `get_usage` only. Data tools answer 403 `forbidden`. | Anyone in the workspace |

Members see and revoke only the keys they created. Owners and admins see every key in the workspace.

## Rotate a key

Keys can't be edited, so rotating means replacing:

1. Create a new key with the same access level.
2. Deploy it where the old key runs.
3. Watch **Last used** for the old key on the API keys page (it updates at most once a minute). When it stops moving, nothing uses it.
4. Revoke the old key.

For short-lived jobs and contractors, set an expiry when you create the key, so it stops working by itself.

## Revoke a key

Click **Revoke** next to the key on the API keys page. The key stops working on every server within a minute, usually at once. Calls with it then answer 401 `unauthorized`. Closing the account stops every key in it.

## Authentication errors

| Status | message | What happened |
| --- | --- | --- |
| 401 | "Missing API key. Send Authorization: Bearer ls_live_…" | No `Authorization` header. |
| 401 | "Invalid API key." | The key is mistyped or doesn't exist. |
| 401 | "This API key was revoked." | Someone revoked it. |
| 401 | "This API key has expired." | Its expiry date passed. |
| 401 | "This account is closed." | The workspace was deleted. |
| 403 | "This key is read only. search_people needs a key with data access." | A read-only key called a data tool. |

A 401 carries `WWW-Authenticate: Bearer realm="leadsets"`. Don't retry a 401 or 403 as is: fix the key, then run again. The error shape is in [Errors and retries](https://www.leadsets.ai/docs/errors).

## Label your client

Optional: send `X-Leadsets-Client: my-app` to name the caller in your [request log](https://www.leadsets.ai/app/requests). Without it, the log shows the client it recognises from the User-Agent (Claude, Cursor, n8n and others), or REST or MCP.

[Previous
**← Quickstart**](https://www.leadsets.ai/docs/quickstart) [Next
**Connect via MCP →**](https://www.leadsets.ai/docs/mcp)

Was this page useful? [Tell us](mailto:support@leadsets.ai?subject=Docs%20feedback%3A%20%2Fdocs%2Fauthentication)

---

Leadsets by Mobylogix LLC, 10160 hwy 242, Conroe, TX, 77385, US. Facts for AI assistants: https://www.leadsets.ai/llm · Site index: https://www.leadsets.ai/llms.txt · Every page: https://www.leadsets.ai/llms-full.txt