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

# How to authenticate your LeadScout REST API requests

> Learn how to authenticate API requests using session cookies or Bearer JWT tokens, and understand the difference between 401 and 403 responses.

Every request to the LeadScout API must be authenticated. The API accepts two authentication methods: a **session cookie** set automatically by the web dashboard after login, and a **Bearer JWT token** intended for the mobile app and external integrations. Both methods resolve to the same user record and produce identical authorization behavior, so you can use whichever fits your client.

## Session cookie (web dashboard)

When you use the LeadScout web dashboard, signing in sets a session cookie automatically. The browser sends that cookie with every API request — you do not need to set any headers manually. This method is not suitable for server-to-server or mobile integrations.

## Bearer JWT token (mobile and integrations)

For programmatic access, obtain an access token for the LeadScout API audience and attach it to every request as an `Authorization` header.

```
Authorization: Bearer <your-access-token>
```

LeadScout validates the token signature and audience on every request. Expired or tampered tokens are rejected with a `401` response.

<Note>
  You must request the token with the correct **API audience** for your environment. Tokens issued for a different audience will be rejected even if the signature is valid.
</Note>

### Obtaining a token

To obtain API access credentials for server-to-server or custom integrations, contact the LeadScout team. They will provide your **client ID**, **client secret**, and **API audience** values. Once you have those, exchange them for a bearer token using the OAuth 2.0 client credentials flow:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://YOUR_TOKEN_ENDPOINT/oauth/token \
    --header 'Content-Type: application/json' \
    --data '{
      "grant_type": "client_credentials",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "audience": "YOUR_API_AUDIENCE"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://YOUR_TOKEN_ENDPOINT/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      audience: 'YOUR_API_AUDIENCE',
    }),
  });

  const { access_token } = await response.json();
  ```
</CodeGroup>

### Making an authenticated request

Once you have a token, pass it in the `Authorization` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://app.leadscoutapp.com/api/prospects \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.leadscoutapp.com/api/prospects', {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });

  const data = await response.json();
  ```
</CodeGroup>

## Error responses

### 401 Unauthorized

You receive a `401` when no credential is present or the provided token is invalid — for example, when the token is expired, the signature does not match, or the audience claim is wrong.

```json theme={null}
{ "error": "Unauthorized" }
```

### 403 Forbidden

You receive a `403` when your credential is valid but your role or permissions do not allow the requested action. For example, a `sales` role user attempting to create a webhook (admin-only) will receive a `403`.

```json theme={null}
{ "error": "Forbidden" }
```

## Roles and permissions

The API enforces three roles with increasing authority:

| Role    | Description                                                                                      |
| ------- | ------------------------------------------------------------------------------------------------ |
| `sales` | Can view and update assigned prospects. Limited to their own data unless granted broader access. |
| `admin` | Can view all prospects, manage team members, create webhooks, and invite users.                  |
| `owner` | All admin permissions, plus billing management.                                                  |

<Tip>
  Individual `sales` users can be granted extra capabilities — `canManageProspects` or `canManageTags` — by an admin or owner without changing their base role.
</Tip>