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.

API keys are the recommended way to authenticate server-to-server integrations with SphereScout. Unlike JWT tokens, API keys do not expire by default, so you don’t need to manage a token-refresh cycle in your code. You can create multiple keys — one per integration or environment — and revoke any key instantly if it is compromised.

​
Create an API key in the dashboard

1

Open the Plans section

Log in to your SphereScout account and navigate to Dashboard → Plans.
2

Go to the API Keys tab

Select the API Keys tab within the Plans section. This page lists all existing keys on your account, showing each key’s prefix, creation date, and expiry date (if set).
3

Create a new key

Click Create API Key. Optionally set an expiry date if you want the key to auto-expire after a specific period. Leave the field blank to create a key with no expiry.
4

Copy and store the key securely

After creation, the dashboard displays the full API key once. Copy it immediately and store it in a secrets manager, environment variable, or another secure location. The dashboard will only show the key prefix (token_key) from this point on — the full key cannot be retrieved again.
The full API key is shown only once at creation time. If you lose it, you must revoke the key and create a new one.

​
Use an API key in requests

Pass your API key in the Authorization header of every request using the Bearer scheme: 
Authorization: Bearer YOUR_API_KEY

curl -G "https://www.spherescout.io/api/companies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "countries=US" \
  --data-urlencode "email=true"
Store your API key in an environment variable (e.g. SPHERESCOUT_API_KEY) and never commit it to source control.

​
Manage keys via the API

You can also manage API keys programmatically using the key management endpoints. These endpoints require authentication with an existing API key or a valid JWT access token.

​
List API keys

Retrieve all keys on your account. The response includes the key prefix (token_key), not the full key value. 
curl "https://www.spherescout.io/api/user/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response fields
​
id
string
required
Unique identifier for the API key. Use this ID to revoke the key.
​
token_key
string
required
The key prefix (first several characters). The full key value is not retrievable after creation.
​
created
string
required
ISO 8601 timestamp of when the key was created.
​
expiry
string | null
required
ISO 8601 expiry date, or null if the key has no expiry.

​
Create an API key

Send a POST request with an optional expiry field. If you omit expiry, the key has no expiry. 
# Create a key with no expiry
curl -X POST "https://www.spherescout.io/api/user/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Create a key that expires on a specific date
curl -X POST "https://www.spherescout.io/api/user/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expiry": "2027-01-01T00:00:00Z"}'
Request body
​
expiry
string
Optional ISO 8601 expiry date and time (e.g. "2027-01-01T00:00:00Z"). Omit to create a key with no expiry.
Response fields
​
token
string
required
The full API key value. Store this immediately — it is only returned once.
​
api_key
object
required
Metadata about the newly created key.

​
Revoke an API key

Send a DELETE request with the key ID. Revocation is permanent and takes effect immediately. Any requests using the revoked key will receive a 401 Unauthorized response. 
curl -X DELETE "https://www.spherescout.io/api/user/api-keys/KEY_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
A successful revocation returns 204 No Content with no response body.
Revoking an API key is irreversible. Any integration using that key will stop working immediately. Rotate credentials by creating a new key before revoking the old one.