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

# Create and manage SphereScout API keys

> Generate long-lived API keys in the SphereScout Dashboard or via the API, then use them to authenticate programmatic requests to the contact database.

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

<Steps>
  <Step title="Open the Plans section">
    Log in to your SphereScout account and navigate to **Dashboard → Plans**.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

## 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
```

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://www.spherescout.io/api/companies" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode "countries=US" \
    --data-urlencode "email=true"
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
  ```
</CodeGroup>

<Tip>
  Store your API key in an environment variable (e.g. `SPHERESCOUT_API_KEY`) and never commit it to source control.
</Tip>

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

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.spherescout.io/api/user/api-keys" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

**Response fields**

<ResponseField name="id" type="string" required>
  Unique identifier for the API key. Use this ID to revoke the key.
</ResponseField>

<ResponseField name="token_key" type="string" required>
  The key prefix (first several characters). The full key value is not retrievable after creation.
</ResponseField>

<ResponseField name="created" type="string" required>
  ISO 8601 timestamp of when the key was created.
</ResponseField>

<ResponseField name="expiry" type="string | null" required>
  ISO 8601 expiry date, or `null` if the key has no expiry.
</ResponseField>

### Create an API key

Send a POST request with an optional `expiry` field. If you omit `expiry`, the key has no expiry.

<CodeGroup>
  ```bash curl theme={null}
  # 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"}'
  ```

  ```python Python theme={null}
  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}")
  ```
</CodeGroup>

**Request body**

<ParamField body="expiry" type="string">
  Optional ISO 8601 expiry date and time (e.g. `"2027-01-01T00:00:00Z"`). Omit to create a key with no expiry.
</ParamField>

**Response fields**

<ResponseField name="token" type="string" required>
  The full API key value. Store this immediately — it is only returned once.
</ResponseField>

<ResponseField name="api_key" type="object" required>
  Metadata about the newly created key.

  <Expandable title="api_key properties">
    <ResponseField name="id" type="string" required>
      Unique key ID. Use this to revoke the key later.
    </ResponseField>

    <ResponseField name="token_key" type="string" required>
      Key prefix shown in the dashboard.
    </ResponseField>

    <ResponseField name="created" type="string" required>
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="expiry" type="string | null" required>
      Expiry date, or `null` if no expiry was set.
    </ResponseField>
  </Expandable>
</ResponseField>

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

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE "https://www.spherescout.io/api/user/api-keys/KEY_ID" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  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}")
  ```
</CodeGroup>

A successful revocation returns `204 No Content` with no response body.

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