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

# Authentication

> API keys, rate limits, and credit usage

## API Keys

All API requests require authentication using an API key. Include your key in the `X-API-Key` header:

```bash theme={null}
curl "https://api.debtstack.ai/v1/companies" \
  -H "X-API-Key: ds_xxxxx"
```

<Warning>
  Keep your API key secure. Never expose it in client-side code or public repositories.
</Warning>

### Getting Your API Key

1. Sign up at [debtstack.ai](https://debtstack.ai)
2. Go to your [Dashboard](https://debtstack.ai/dashboard)
3. Copy your API key from the API Keys section

### Key Format

API keys follow the format `ds_` followed by 32 hexadecimal characters:

```
ds_a1b2c3d4e5f6789012345678abcdef12
```

## Rate Limits

Rate limits are applied per API key based on your tier:

| Tier          | Rate Limit | Queries      |
| ------------- | ---------- | ------------ |
| Pay-as-You-Go | 60/min     | Pay per call |
| Pro           | 100/min    | Unlimited    |
| Business      | 500/min    | Unlimited    |

### Rate Limit Headers

Every response includes rate limit information:

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706140800
```

### Handling Rate Limits

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "details": {
      "retry_after": 30
    }
  }
}
```

Check the `Retry-After` header for when you can retry.

## Credit System (Pay-as-You-Go)

Pay-as-You-Go users pay per API call based on endpoint complexity:

| Endpoint Type | Cost   | Endpoints                                                                                              |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| Simple        | \$0.05 | `/v1/companies`, `/v1/bonds`, `/v1/bonds/resolve`, `/v1/financials`, `/v1/collateral`, `/v1/covenants` |
| Complex       | \$0.10 | `/v1/companies/{ticker}/changes`                                                                       |
| Advanced      | \$0.15 | `/v1/entities/traverse`, `/v1/documents/search`, `/v1/batch`                                           |

### Credit Packages

Pre-purchase credits for predictable budgeting:

| Package | Approximate Queries    |
| ------- | ---------------------- |
| \$10    | \~200 simple queries   |
| \$25    | \~500 simple queries   |
| \$50    | \~1,000 simple queries |
| \$100   | \~2,000 simple queries |

Credits never expire and remain in your account until used.

### Checking Credit Balance

```bash theme={null}
curl "https://api.debtstack.ai/v1/auth/me" \
  -H "X-API-Key: ds_xxxxx"
```

Response:

```json theme={null}
{
  "email": "user@example.com",
  "tier": "pay_as_you_go",
  "credits": {
    "remaining": 4500,
    "resets_at": null
  }
}
```

## Pricing Tiers

<CardGroup cols={3}>
  <Card title="Pay-as-You-Go" icon="coins">
    **\$0/month + usage**

    * Pay per API call ($0.05-$0.15)
    * 60 requests/minute
    * 211 companies
    * All basic endpoints
    * No monthly commitment
  </Card>

  <Card title="Pro" icon="rocket">
    **\$199/month**

    * Unlimited API queries
    * 100 requests/minute
    * 211 companies
    * All basic endpoints
    * Email support (48hr)
  </Card>

  <Card title="Business" icon="building">
    **\$499/month**

    * Everything in Pro, plus:
    * 500 requests/minute
    * 5 team seats
    * Covenant comparison
    * Historical bond pricing
    * Bulk data export
    * Usage analytics
    * Priority support (24hr)
    * 99.9% uptime SLA
  </Card>
</CardGroup>

### Business-Only Endpoints

These advanced endpoints are exclusively available on the Business tier:

| Endpoint                            | Description                                 |
| ----------------------------------- | ------------------------------------------- |
| `/v1/covenants/compare`             | Compare covenants across multiple companies |
| `/v1/bonds/{cusip}/pricing/history` | Historical bond pricing (up to 2 years)     |
| `/v1/export`                        | Bulk data export (up to 50,000 records)     |
| `/v1/usage/analytics`               | Detailed usage analytics and trends         |

For Business tier inquiries, [contact us](mailto:hello@debtstack.ai).

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use environment variables">
    Store your API key in environment variables, not in code:

    ```python theme={null}
    import os
    API_KEY = os.environ.get("DEBTSTACK_API_KEY")
    ```
  </Accordion>

  <Accordion title="Rotate keys periodically">
    You can regenerate your API key from the dashboard. The old key will be immediately invalidated.
  </Accordion>

  <Accordion title="Monitor usage">
    Check your usage regularly in the dashboard to detect any unauthorized access.
  </Accordion>
</AccordionGroup>