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

# Authentication

> Exchange your client credentials for a Bearer token, understand scopes, and learn which account a token acts for.

Every request except the token exchange carries `Authorization: Bearer <token>`. There are two ways to obtain a token. Server integrations use client credentials. People using the Leadinfo MCP sign in with their Leadinfo account through OAuth; the MCP client takes care of that flow and the resulting token acts for the person who signed in.

## Client credentials

**1. Request a token**

Call `POST /v1/auth/token` with your credentials in the request headers.

**X-Client-ID** `string` *required*

Your Leadinfo client identifier.

**X-Client-Secret** `string` *required*

Your Leadinfo client secret.

```bash cURL theme={null}
curl --request POST \
  --url https://data.leadinfo.com/v1/auth/token \
  --header "X-Client-ID: <your-client-id>" \
  --header "X-Client-Secret: <your-secret>"
```

```python Python theme={null}
import requests

response = requests.post(
    "https://data.leadinfo.com/v1/auth/token",
    headers={
        "X-Client-ID": "<your-client-id>",
        "X-Client-Secret": "<your-secret>",
    },
)
response.raise_for_status()
token = response.json()
```

The response carries the token, its lifetime in seconds and the scopes granted to your client:

```json theme={null}
{
  "access_token": "531f33…",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "read tracker:read"
}
```

Use `expires_in` from the response rather than a fixed number; lifetimes differ per client.

**2. Use the token**

**Authorization** `string` *required*

`Bearer <access_token>`

```bash cURL theme={null}
curl --request GET \
  --url "https://data.leadinfo.com/v1/trackers" \
  --header "Authorization: Bearer <token>"
```

**3. Renew before expiry**

Request a new token shortly before `expires_in` seconds have passed. An expired or unknown token gets `401 Unauthorized`.

## Scopes

Scopes are granted to your client by Leadinfo and appear in the `scope` field of the token response and of `GET /v1/auth/me`.

| Scope | What it allows |
| - | - |
| `read` | Default scope on every token. |
| `tracker:read` | All account and tracker data: trackers, tags, segments, companies, scores, sessions, identified visitors, form and Leadbot submissions, the scoring model and profile suggestions. |

Identified visitors and Leadbot conversations are visible to anyone with `tracker:read`, the same as in the Portal. A request that needs a scope the token lacks gets `403 Forbidden` with the missing scope in the message.

## Who a token acts for

`GET /v1/auth/me` tells you.

| Field | Meaning |
| - | - |
| `client_id`, `client_name` | The OAuth client the token was issued to. |
| `scope` | Space-separated granted scopes. |
| `token_expires_at` | Expiry of this token. |
| `company_id` | The Leadinfo company the token acts for. |
| `user_id`, `customer_id` | Set on tokens obtained by a person signing in (the Leadinfo MCP); `null` on client-credentials tokens. |
| `is_partner`, `managed_companies` | Whether the account manages other companies' trackers, and how many. |
| `trackers`, `trackers_with_traffic`, `tags`, `segments`, `personas` | Counts for the visible account. |

A client-credentials token acts for the company that owns the client. A token obtained by a person acts for that person's company. Partner accounts see their own trackers and those of the companies they manage.

## Errors

| Status | Meaning |
| - | - |
| `401 Unauthorized` | Missing, malformed, unknown or expired token, or wrong client credentials on `/v1/auth/token`. |
| `403 Forbidden` | Valid token without the required scope, or a tracker that does not belong to the account. |
| `422 Unprocessable Entity` | Invalid parameters, for example an inverted date range or an unsupported filter rule. |
| `429 Too Many Requests` | Rate limit exceeded; see [Limits](https://docs.leadinfo.com/limits.md). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.