Authenticate requests to the SphereScout API

Every request to a protected SphereScout endpoint must include an Authorization header. The API supports two authentication methods: API keys for server-to-server integrations and JWT bearer tokens for user-session-based applications. Both use the same header format — only the credential type differs.

Choose an authentication method

	API keys	JWT tokens
Best for	Server integrations, scripts, automation	User-facing apps, per-user sessions
Lifetime	No expiry by default (or set a custom expiry)	Short-lived; must be refreshed
Setup	Generate once in the Dashboard	Login endpoint → access + refresh tokens
Complexity	Low	Higher (requires token-refresh logic)

For most integrations, API keys are the simpler and more reliable choice. Use JWT tokens only when your application needs to act on behalf of a specific logged-in user.

API key authentication

API keys are long-lived credentials that you generate in the Dashboard or via the API. Include your API key directly as the Bearer token in every request.

Authorization: Bearer YOUR_API_KEY

curl "https://www.spherescout.io/api/user/profile" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

API_KEY = "YOUR_API_KEY"

response = requests.get(
    "https://www.spherescout.io/api/user/profile",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
response.raise_for_status()
profile = response.json()
print(profile)

See API keys for how to create, list, and revoke keys.

JWT token authentication

JWT authentication involves three steps: logging in to obtain tokens, using the access token in requests, and refreshing the access token before it expires.

Step 1 — Obtain tokens

Send a POST request to /api/auth/login with your account credentials. The response contains an access token and a refresh token. Request

string

required

Your account email address. The field is named username in the request body.

string

required

Your account password.

curl -X POST "https://www.spherescout.io/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "you@example.com",
    "password": "your-password"
  }'

import requests

response = requests.post(
    "https://www.spherescout.io/api/auth/login",
    json={
        "username": "you@example.com",
        "password": "your-password",
    },
)
response.raise_for_status()
tokens = response.json()

access_token = tokens["access"]
refresh_token = tokens["refresh"]
print(f"Access token: {access_token[:20]}...")

Response fields

string

required

Short-lived JWT access token. Use this as your Bearer token in subsequent requests.

string

required

Long-lived refresh token. Use this to obtain a new access token when the current one expires. Store this token securely — treat it like a password.

object

Account information returned at login.

Show user properties

string

Unique account identifier.

string

Account email address.

string

First name on the account.

string

Last name on the account.

number

Credits available for exports this billing period.

string

Current subscription plan name.

Step 2 — Use the access token

Include the access token as a Bearer token in the Authorization header of every request:

Authorization: Bearer ACCESS_TOKEN

curl "https://www.spherescout.io/api/companies?countries=DE&email=true" \
  -H "Authorization: Bearer ACCESS_TOKEN"

import requests

headers = {"Authorization": f"Bearer {access_token}"}

response = requests.get(
    "https://www.spherescout.io/api/companies",
    headers=headers,
    params={"countries": "DE", "email": "true"},
)
response.raise_for_status()
data = response.json()
print(f"Total contacts: {data['totalCount']}")

Step 3 — Refresh the access token

Access tokens expire after a short period. When a request returns 401 Unauthorized, exchange your refresh token for a new access token by calling POST /api/token/refresh. Request

string

required

The refresh token you received when you logged in.

curl -X POST "https://www.spherescout.io/api/token/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh": "YOUR_REFRESH_TOKEN"}'

import requests

def refresh_access_token(refresh_token: str) -> str:
    response = requests.post(
        "https://www.spherescout.io/api/token/refresh",
        json={"refresh": refresh_token},
    )
    response.raise_for_status()
    data = response.json()
    return data["access"]

# Call when you receive a 401
new_access_token = refresh_access_token(refresh_token)

Response fields

string

required

A new short-lived access token. Replace the expired token in your application with this value.

string

A new refresh token, if token rotation is enabled. Update your stored refresh token if this field is present in the response.

Error responses

401 Unauthorized

A 401 response means your credential is missing, invalid, or expired.

{
  "detail": "Authentication credentials were not provided."
}

{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid"
}

What to do:

API key: Verify the key is correctly copied and has not been revoked in the Dashboard.
JWT access token: The token has expired. Call POST /api/token/refresh with your refresh token to get a new access token.
JWT refresh token: If the refresh call also returns 401, the refresh token has expired or been invalidated. Re-authenticate by calling POST /api/auth/login again.

Full JWT refresh pattern

The following Python example shows a complete pattern for handling token expiry automatically:

Python

import requests

BASE_URL = "https://www.spherescout.io"

class SphereScoutClient:
    def __init__(self, email: str, password: str):
        self.email = email
        self.password = password
        self.access_token: str | None = None
        self.refresh_token: str | None = None

    def login(self) -> None:
        response = requests.post(
            f"{BASE_URL}/api/auth/login",
            json={"username": self.email, "password": self.password},
        )
        response.raise_for_status()
        data = response.json()
        self.access_token = data["access"]
        self.refresh_token = data["refresh"]

    def _refresh(self) -> None:
        if not self.refresh_token:
            raise RuntimeError("No refresh token — call login() first")
        response = requests.post(
            f"{BASE_URL}/api/token/refresh",
            json={"refresh": self.refresh_token},
        )
        response.raise_for_status()
        data = response.json()
        self.access_token = data["access"]
        if "refresh" in data:
            self.refresh_token = data["refresh"]

    def get(self, path: str, **kwargs) -> dict:
        headers = {"Authorization": f"Bearer {self.access_token}"}
        response = requests.get(f"{BASE_URL}{path}", headers=headers, **kwargs)
        if response.status_code == 401:
            self._refresh()
            headers["Authorization"] = f"Bearer {self.access_token}"
            response = requests.get(f"{BASE_URL}{path}", headers=headers, **kwargs)
        response.raise_for_status()
        return response.json()


# Usage
client = SphereScoutClient("you@example.com", "your-password")
client.login()
data = client.get("/api/companies", params={"countries": "US", "email": "true"})
print(f"Found {data['totalCount']} contacts")

Summary

For server-to-server integrations, use an API key — it requires no token management and works with a single header on every request. Reserve JWT tokens for applications where individual users log in with their own SphereScout credentials.

Get Started

Core Concepts

Using SphereScout

Plans & Billing

API Access

Help

Authenticate requests to the SphereScout API

Choose an authentication method

API key authentication

JWT token authentication

Step 1 — Obtain tokens

Step 2 — Use the access token

Step 3 — Refresh the access token

Error responses

401 Unauthorized

Full JWT refresh pattern

Summary

​Choose an authentication method

​API key authentication

​JWT token authentication

​Step 1 — Obtain tokens

​Step 2 — Use the access token

​Step 3 — Refresh the access token

​Error responses

​401 Unauthorized

​Full JWT refresh pattern

​Summary

Choose an authentication method

API key authentication

JWT token authentication

Step 1 — Obtain tokens

Step 2 — Use the access token

Step 3 — Refresh the access token

Error responses

401 Unauthorized

Full JWT refresh pattern

Summary