Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spherescout.io/llms.txt

Use this file to discover all available pages before exploring further.

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 keysJWT tokens
Best forServer integrations, scripts, automationUser-facing apps, per-user sessions
LifetimeNo expiry by default (or set a custom expiry)Short-lived; must be refreshed
SetupGenerate once in the DashboardLogin endpoint → access + refresh tokens
ComplexityLowHigher (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"
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
​
username
string
required
Your account email address. The field is named username in the request body.
​
password
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"
  }'
Response fields
​
access
string
required
Short-lived JWT access token. Use this as your Bearer token in subsequent requests.
​
refresh
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.
​
user
object
Account information returned at login.

​
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"

​
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
​
refresh
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"}'
Response fields
​
access
string
required
A new short-lived access token. Replace the expired token in your application with this value.
​
refresh
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.