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.

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

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

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

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.

Create a key

1. Open API 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.

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

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.

Label your client

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

Was this page useful? Tell us