Create and manage SphereScout API keys

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

Open the Plans section

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

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.

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"

import requests

API_KEY = "YOUR_API_KEY"

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

const API_KEY = process.env.SPHERESCOUT_API_KEY!;

const response = await fetch(
  "https://www.spherescout.io/api/companies?countries=US&email=true",
  {
    headers: { Authorization: `Bearer ${API_KEY}` },
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(`Total contacts: ${data.totalCount}`);

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"

import requests

response = requests.get(
    "https://www.spherescout.io/api/user/api-keys",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
keys = response.json()
for key in keys:
    print(key["id"], key["token_key"], key["created"], key["expiry"])

Response fields

string

required

Unique identifier for the API key. Use this ID to revoke the key.

string

required

The key prefix (first several characters). The full key value is not retrievable after creation.

string

required

ISO 8601 timestamp of when the key was created.

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

import requests

# No expiry
response = requests.post(
    "https://www.spherescout.io/api/user/api-keys",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={},
)
result = response.json()

# Save the full token immediately — it won't be shown again
new_key = result["token"]
key_info = result["api_key"]
print(f"New key ID: {key_info['id']}")
print(f"Full key (save this now): {new_key}")

Request body

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

string

required

The full API key value. Store this immediately — it is only returned once.

object

required

Metadata about the newly created key.

Show api_key properties

string

required

Unique key ID. Use this to revoke the key later.

string

required

Key prefix shown in the dashboard.

string

required

ISO 8601 creation timestamp.

string | null

required

Expiry date, or null if no expiry was set.

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"

import requests

key_id = "the-key-id-to-revoke"

response = requests.delete(
    f"https://www.spherescout.io/api/user/api-keys/{key_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

if response.status_code == 204:
    print("Key revoked successfully")
else:
    print(f"Error: {response.status_code}")

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.

Get Started

Core Concepts

Using SphereScout

Plans & Billing

API Access

Help

Create and manage SphereScout API keys

Create an API key in the dashboard

Use an API key in requests

Manage keys via the API

List API keys

Create an API key

Revoke an API key

​Create an API key in the dashboard

​Use an API key in requests

​Manage keys via the API

​List API keys

​Create an API key

​Revoke an API key

Create an API key in the dashboard

Use an API key in requests

Manage keys via the API

List API keys

Create an API key

Revoke an API key