> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docketstream.org/llms.txt
> Use this file to discover all available pages before exploring further.

# DocketStream API Authentication: API Keys and Bearer Tokens

> Learn how to generate a DocketStream API key, pass it as a Bearer token, and handle common authentication errors in your integration.

All DocketStream API requests must include a valid API key in the `Authorization` header. The API uses **Bearer token authentication** — every call you make must carry the token, regardless of the HTTP method or endpoint. Requests made without a key, or with an invalid or expired key, are rejected before any data is returned.

## Get Your API Key

API keys are generated from your DocketStream account dashboard. You must be on the **Enterprise plan** before the API Keys section is available.

<Steps>
  <Step title="Log in to DocketStream">
    Navigate to [docketstream.org](https://www.docketstream.org) and sign in to
    your Enterprise account.
  </Step>

  <Step title="Open Account Settings">
    Click your profile avatar in the top-right corner and select **Account
    Settings** from the dropdown menu.
  </Step>

  <Step title="Navigate to API Keys">
    In the left sidebar of Account Settings, select **API Keys**.
  </Step>

  <Step title="Generate a New Key">
    Click **Generate New Key**, optionally give it a descriptive label (e.g.,
    "Production Integration"), and confirm.
  </Step>

  <Step title="Copy and store the key securely">
    Your new API key is displayed **only once**. Copy it immediately and store
    it in a secure secrets manager or environment variable. You cannot retrieve
    the key again after closing the dialog — if you lose it, you must revoke it
    and generate a new one.
  </Step>
</Steps>

<Warning>
  API keys grant **full API access** to your DocketStream account, including
  reading sensitive correctional records and managing alert watchers. Treat your
  key exactly like a password — never share it, never log it, and rotate it
  immediately if you suspect it has been compromised.
</Warning>

## Pass the Key in Requests

Include your API key in the `Authorization` header of every request using the `Bearer` scheme:

```bash theme={null}
curl -X GET https://api.docketstream.org/v1/roster \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

Replace `YOUR_API_KEY` with the key you copied from Account Settings.

## Code Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.docketstream.org/v1/roster?county=clayton \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"
  BASE_URL = "https://api.docketstream.org/v1"

  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json",
  }

  response = requests.get(
      f"{BASE_URL}/roster",
      headers=headers,
      params={"county": "clayton", "limit": 50},
  )

  response.raise_for_status()
  data = response.json()
  print(data)
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = process.env.DOCKETSTREAM_API_KEY;
  const BASE_URL = "https://api.docketstream.org/v1";

  const response = await fetch(`${BASE_URL}/roster?county=clayton&limit=50`, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    throw new Error(`DocketStream API error: ${response.status}`);
  }

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Authentication Error Responses

If your request cannot be authenticated or authorized, the API returns one of the following error responses:

| HTTP Status | Error Code     | Meaning                                                 |
| ----------- | -------------- | ------------------------------------------------------- |
| `401`       | `unauthorized` | API key is missing, malformed, or invalid               |
| `403`       | `forbidden`    | Key is valid, but your plan does not include API access |
| `429`       | `rate_limited` | You have exceeded 100 requests per minute               |

All error responses include a JSON body with `error` and `message` fields:

```json theme={null}
{
  "error": "unauthorized",
  "message": "No valid API key was provided. Include your key in the Authorization header as a Bearer token."
}
```

## Security Best Practices

<Tip>
  Follow these practices to keep your API key — and the sensitive data it
  accesses — secure.
</Tip>

* **Use environment variables.** Never hard-code your API key in source files. Load it at runtime from an environment variable (e.g., `DOCKETSTREAM_API_KEY`) or a secrets manager such as AWS Secrets Manager or HashiCorp Vault.
* **Never commit keys to source control.** Add `.env` files to your `.gitignore`. Audit your repository history if you suspect a key was ever committed, and rotate it immediately.
* **Rotate keys regularly.** Return to **Account Settings → API Keys** to revoke old keys and generate new ones as part of your security hygiene routine.
* **Use separate keys per environment.** Generate distinct keys for development, staging, and production so you can revoke one without affecting the others.
* **Restrict key exposure.** Only the services and team members that need API access should have the key. Do not paste it into chat messages, tickets, or emails.