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

# Authentication

> Authenticate your API requests using API keys

## Overview

All Yield.xyz API requests require authentication using an API key. API keys are passed in the `x-api-key` header.

<Card title="Get Your API Key" icon="key" href="https://dashboard.yield.xyz/sign-up/register-interest" horizontal>
  Sign up to create your API key
</Card>

***

## API Key Format

API keys follow this format:

```
1a2b3c4d5e6f7g8h9i0j...  // Production key
9z8y7x6w5v4u3t2s1r0q...  // Test key
```

<Tip>
  Test keys only work with testnets. Production keys work with mainnets.
</Tip>

***

## Making Authenticated Requests

Include your API key in the `x-api-key` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.yield.xyz/v1/yields \
    -H "x-api-key: your_api_key_here"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.yield.xyz/v1/yields', {
    headers: {
      'x-api-key': process.env.YIELD_API_KEY
    }
  });
  ```

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

  headers = {
      'x-api-key': 'your_api_key_here'
  }

  response = requests.get(
      'https://api.yield.xyz/v1/yields',
      headers=headers
  )
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.get('https://api.yield.xyz/v1/yields', {
    headers: {
      'x-api-key': process.env.YIELD_API_KEY
    }
  });
  ```
</CodeGroup>

***

## Error Responses

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "message": "Invalid API key",
  "error": "Unauthorized",
  "statusCode": 401
}
```

**Common causes:**

* API key is missing from the header
* API key is invalid or expired
* API key has been revoked
* Wrong header name (use `x-api-key`, not `X-API-KEY` or `Authorization`)

### 403 Forbidden

API key is valid but lacks required permissions:

```json theme={null}
{
  "message": "Access denied from US (US-CA)",
  "error": "Forbidden",
  "statusCode": 403
}
```

**Common causes:**

* Geoblocking restrictions
* Read-only key used for write operations
* API key disabled in dashboard

### 429 Rate Limited

Too many requests:

```json theme={null}
{
  "message": "Rate limit exceeded",
  "error": "Too Many Requests",
  "statusCode": 429,
  "retryAfter": 30
}
```

**Response headers:**

```
x-ratelimit-limit: 100
x-ratelimit-remaining: 0
x-ratelimit-reset: 1698765432
retry-after: 30
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Store keys securely">
    **Never** commit API keys to version control. Use environment variables:

    ```bash .env theme={null}
    YIELD_API_KEY=abc123...
    ```
  </Accordion>

  <Accordion title="Use backend-only">
    Make API calls from your backend, not client-side JavaScript:

    ```typescript theme={null}
    // ❌ Bad - exposes API key in browser
    const apiKey = 'abc123...';

    // ✅ Good - API key stays on server
    const apiKey = process.env.YIELD_API_KEY;
    ```
  </Accordion>

  <Accordion title="Separate keys per environment">
    Use different API keys for development, staging, and production:

    ```bash theme={null}
    YIELD_API_KEY_DEV=test_...
    YIELD_API_KEY_STAGING=test_...
    YIELD_API_KEY_PROD=live_...
    ```
  </Accordion>

  <Accordion title="Rotate regularly">
    Generate new keys periodically and revoke old ones in your [dashboard](https://dashboard.yield.xyz/api-keys).
  </Accordion>

  <Accordion title="Monitor usage">
    Track API usage in your dashboard to detect anomalies or unauthorized access.
  </Accordion>
</AccordionGroup>

***

## Rate Limits

Rate limits vary by plan:

| Plan           | Requests/Second | Requests/Month |
| -------------- | --------------- | -------------- |
| **Free**       | 10              | 100,000        |
| **Starter**    | 50              | 1,000,000      |
| **Pro**        | 200             | 10,000,000     |
| **Enterprise** | Custom          | Unlimited      |

<Card title="View Rate Limits" icon="gauge" href="/getting-started/rate-limits-and-plans" horizontal>
  Learn more about rate limits and plans
</Card>

***

## Environments

### Production

```
https://api.yield.xyz
```

Use production keys (`live_...`) for mainnet transactions.

### Staging

```
https://api.staging.yield.xyz
```

Use test keys (`test_...`) for testing against staging environment.

***

## Testing Authentication

Verify your API key works:

```bash theme={null}
curl https://api.yield.xyz/v1/yields?limit=1 \
  -H "x-api-key: your_api_key_here"
```

**Success response:**

```json theme={null}
{
  "items": [...],
  "total": 150,
  "offset": 0,
  "limit": 1
}
```

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Create API Key" icon="key" href="/getting-started/creating-api-key">
    Step-by-step guide to creating your first API key
  </Card>

  <Card title="List Yields" icon="list" href="/api-reference/yields/list-yields">
    Make your first API call
  </Card>

  <Card title="Project Setup" icon="rocket" href="/getting-started/project-setup">
    Complete integration guide
  </Card>
</CardGroup>