> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leadterra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate Your Requests to the Leadterra Email API

> Leadterra uses Bearer token authentication. Pass your API key in the Authorization header on every request to authenticate securely.

Every request to the Leadterra API must be authenticated with a Bearer token. You include your API key in the `Authorization` header, and Leadterra uses it to identify your workspace, enforce rate limits, and scope access to your campaigns, sender pools, and leads. There are no session cookies, no OAuth flows, and no multi-step handshakes — just a single header on every call.

## Getting your API key

Log in to your workspace at [app.leadterra.co](https://app.leadterra.co) and go to **Settings → API Keys**. Click **Create new key**, give it a descriptive label (for example, `production-agent` or `ci-pipeline`), and copy the value immediately — Leadterra only shows the full key once at creation time.

Your API key will look like this:

```text theme={null}
sk_live_YOUR_KEY
```

The `sk_live_` prefix confirms it is a live key scoped to your production workspace. If you need to test without affecting real campaigns, check whether your workspace supports a sandbox environment with `sk_test_` prefixed keys.

## Making authenticated requests

Include your API key as a Bearer token in the `Authorization` header of every request.

```text theme={null}
Authorization: Bearer sk_live_YOUR_KEY
```

Here is a complete example that lists the sender pools in your workspace:

```bash theme={null}
curl https://app.leadterra.co/v1/sender-pools \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
```

Replace `sk_live_YOUR_KEY` with the key you copied from the dashboard. The same header format applies to every endpoint — `GET`, `POST`, or otherwise.

<Warning>
  Never share your API key or expose it in client-side code, public repositories, or log output. Anyone with your key can access your workspace, send emails on your behalf, and read your lead data.
</Warning>

## API key security

Following these practices keeps your key safe and your workspace protected:

* **Use environment variables.** Store your key in a variable like `LEADTERRA_API_KEY` and reference it in code rather than hard-coding the value.
* **Never commit keys to source control.** Add `.env` files to your `.gitignore` and audit your repository history if you suspect a key was ever committed.
* **Restrict key scope when possible.** Create separate keys for separate systems (agents, CI pipelines, local scripts) so you can rotate one without affecting the others.
* **Rotate immediately if compromised.** If a key is exposed, go to **Settings → API Keys**, revoke it, and issue a new one. Update all systems that use the old key before the next deployment.
* **Audit key usage.** Review active keys periodically and delete any that are no longer in use.

## Authentication errors

If your request is rejected due to an authentication problem, the API returns a `401` or `403` status code.

| Status             | Meaning                                                               | What to do                                                                                            |
| ------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | No `Authorization` header was sent, or the header is malformed.       | Confirm the header is present and formatted as `Bearer sk_live_YOUR_KEY`.                             |
| `401 Unauthorized` | The API key is invalid or has been revoked.                           | Verify the key value in your dashboard. If it was revoked, create a new one.                          |
| `403 Forbidden`    | The key is valid but does not have permission to perform this action. | Check that you are using the correct key for this workspace and that the key has not been restricted. |

<Info>
  If you keep receiving `401` errors even with what looks like a valid key, make sure there are no extra spaces, newline characters, or truncated characters in the key value — copy-paste errors are the most common cause.
</Info>