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

# API keys, usage, and billing

> Authenticate machine requests with x-api-key, inspect the account that will run them, and keep billing controls in the dashboard

Use an API key for REST, SDK, CLI, and server-to-server MCP requests. Use the signed-in [SEC API dashboard](https://secapi.ai/app) for people-driven actions such as creating keys and changing billing settings.

## Make the first authenticated check

```bash theme={null}
export SECAPI_API_KEY="secapi_..."

curl --fail-with-body -sS \
  -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/limits"
```

Send the key in `x-api-key`. Do not send it as `Authorization: Bearer`, place it in a URL or request body, expose it in browser-delivered code, or commit it to source control.

## Use the right credential for each action

| Job                                                                  | Credential and location                                                   |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Read SEC data from code, an SDK, CLI, or server-to-server MCP client | API key in `x-api-key`, held by your server, worker, shell, or MCP client |
| Create, reveal, rotate, or revoke an API key                         | Signed-in dashboard session                                               |
| Change billing, payment methods, or budgets                          | Signed-in dashboard session with the required access                      |

A dashboard session is not a substitute for an API key on a data request. An API key cannot manage dashboard billing or create another key.

## Inspect the account before repeated work

Use the same key that will run the workload to check that account's billing state and limits:

```bash theme={null}
curl --fail-with-body -sS -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/billing"

curl --fail-with-body -sS -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/limits"
```

Read `GET /v1/billing/rates` as the public current rate catalog; it is not account-specific billing state:

```bash theme={null}
curl --fail-with-body -sS \
  "https://api.secapi.ai/v1/billing/rates"
```

`GET /v1/billing` and `GET /v1/limits` describe the authenticated account context, so recheck them when changing keys or expanding a workload. For a repeated or expensive path, use `POST /v1/billing/quote` with that key: it estimates the requested path against the current account and budget gate. It is not a reservation or a promise for a later request.

## Read metering and retry signals

For production requests, retain `Request-Id` and `traceparent` when present. Also retain `SECAPI-Meter-Class`, `SECAPI-Estimated-Cost`, `SECAPI-Token-Count`, and `Retry-After` when supplied. They describe that response only; check billing and limits again before expanding a workload.

## Rotate a key without interrupting callers

1. Create a replacement key in the dashboard.
2. Update the server-side secret where the application runs.
3. Verify the replacement with `GET /v1/limits`.
4. Revoke the old key after callers use the replacement.

For a suspected leak, revoke the exposed key before creating and deploying its replacement. Continue with [API conventions](/api-conventions) for response behavior, [billing-aware agent runs](/agent-billing) for automated workloads, or [plans and pricing](/plans-and-pricing) for rights and plan boundaries.