How to authenticate your LeadScout REST API requests

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. 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.

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.

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:

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"
  }'

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();

Making an authenticated request

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

curl --request GET \
  --url https://app.leadscoutapp.com/api/prospects \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

const data = await response.json();

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.

{ "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.

{ "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.

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

Overview

Endpoints

How to authenticate your LeadScout REST API requests

Bearer JWT token (mobile and integrations)

Obtaining a token

Making an authenticated request

Error responses

401 Unauthorized

403 Forbidden

Roles and permissions

​Session cookie (web dashboard)

​Bearer JWT token (mobile and integrations)

​Obtaining a token

​Making an authenticated request

​Error responses

​401 Unauthorized

​403 Forbidden

​Roles and permissions

Session cookie (web dashboard)

Bearer JWT token (mobile and integrations)

Obtaining a token

Making an authenticated request

Error responses

401 Unauthorized

403 Forbidden

Roles and permissions