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

# Authentication

> Learn how to authenticate with the Pods API

Pods API uses API keys to authenticate most requests. Include your API key in the `x-api-key` header for swap, strategy, wallet, and tracking endpoints.

<Note>
  `GET /health` is public and does not require authentication. Customer dashboard endpoints (`GET /customers/me`, `/customers/:id/tokens`, `/customers/:id/token-groups`) require a **Bearer** token (Supabase or Magic JWT) — API key alone is not sufficient because those routes enforce user role checks.
</Note>

## Getting an API Key

<Steps>
  <Step title="Sign up for Pods">
    Create an account at [pods.finance](https://pods.finance)
  </Step>

  <Step title="Navigate to API Keys">
    Go to the **API Keys** section in your dashboard
  </Step>

  <Step title="Generate New Key">
    Click "Generate API Key" and give it a descriptive name
  </Step>

  <Step title="Copy and Store">
    Copy your API key immediately - you won't be able to see it again!
  </Step>
</Steps>

<Warning>
  **Keep your API keys secure!** Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.
</Warning>

## Using Your API Key

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

<CodeGroup>
  ```javascript JavaScript/TypeScript theme={null}
  import axios from 'axios'

  const pods = axios.create({
    baseURL: 'https://api.pods.finance',
    headers: {
      'x-api-key': process.env.PODS_API_KEY
    }
  })

  // Make authenticated request
  const response = await pods.get('/strategies')
  ```

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

  headers = {
      'x-api-key': os.getenv('PODS_API_KEY')
  }

  response = requests.get(
      'https://api.pods.finance/strategies',
      headers=headers
  )
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.pods.finance/strategies" \
    -H "x-api-key: $PODS_API_KEY"
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      client := &http.Client{}
      req, _ := http.NewRequest("GET", "https://api.pods.finance/strategies", nil)

      req.Header.Add("x-api-key", os.Getenv("PODS_API_KEY"))

      resp, _ := client.Do(req)
  }
  ```
</CodeGroup>

<Note>
  Store your API key in a secure server-side environment variable (e.g. `PODS_API_KEY`).
  Do not expose it in frontend code or commit it to git.
</Note>

## API Key Authentication

**Recommended for all integrations**

Use the `x-api-key` header for all API requests:

```javascript theme={null}
headers: {
  'x-api-key': 'your-api-key'
}
```

**Best for:**

* Backend services
* Server-to-server communication
* Automated scripts and bots
* CI/CD pipelines
* All application types

<Note>
  API keys are tied to your customer account and can be rotated or revoked at any time from your dashboard.
</Note>

## Bearer Token Authentication

**Required for customer dashboard endpoints**

Use a Supabase or Magic JWT in the `Authorization` header for routes such as `GET /customers/me`, `/customers/:id/tokens`, and `/customers/:id/token-groups`:

```javascript theme={null}
headers: {
  Authorization: 'Bearer your-jwt-token'
}
```

These routes enforce user role checks (`admin`, `owner`, `developer`, `viewer`). API key authentication alone does not satisfy those checks even when the key is valid.

**Best for:**

* Customer dashboard and admin UI
* Token group and wallet token management
* Profile and account settings (`GET /customers/me`)

## Rate Limits

API keys are subject to rate limits to ensure fair usage:

<Card title="Rate Limits" icon="gauge-high">
  * **100 requests per minute** per API key
  * **1,000 requests per hour** per API key
</Card>

### Handling Rate Limits

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

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "details": {
      "retryAfter": 60
    }
  }
}
```

<CodeGroup>
  ```javascript JavaScript theme={null}
  import axios from 'axios'

  const pods = axios.create({
    baseURL: 'https://api.pods.finance',
    headers: { 'x-api-key': process.env.PODS_API_KEY }
  })

  // Add rate limit handling
  pods.interceptors.response.use(
    response => response,
    async error => {
      if (error.response?.status === 429) {
        const retryAfter = error.response.data.error.details.retryAfter
        console.log(`Rate limited. Retrying after ${retryAfter}s...`)

        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))

        // Retry the request
        return pods(error.config)
      }
      return Promise.reject(error)
    }
  )
  ```

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

  def make_request_with_retry(url, headers, max_retries=3):
      for attempt in range(max_retries):
          response = requests.get(url, headers=headers)

          if response.status_code == 429:
              retry_after = response.json()['error']['details']['retryAfter']
              print(f"Rate limited. Waiting {retry_after}s...")
              time.sleep(retry_after)
              continue

          return response

      raise Exception("Max retries exceeded")
  ```
</CodeGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store Keys Securely" icon="lock">
    Never hardcode API keys in your source code.

    **Do:**

    * Use environment variables
    * Use secret management services (AWS Secrets Manager, HashiCorp Vault)
    * Use encrypted configuration files

    **Don't:**

    * Commit keys to version control
    * Include keys in client-side code
    * Share keys via email or messaging apps
  </Accordion>

  <Accordion title="Rotate Keys Regularly" icon="rotate">
    Rotate your API keys periodically to minimize security risks.

    **Recommended rotation schedule:**

    * Production keys: Every 90 days
    * Development keys: Every 180 days
    * Immediately if compromised

    **How to rotate:**

    1. Generate a new API key in your dashboard
    2. Update your application with the new key
    3. Test that the new key works
    4. Delete the old key
  </Accordion>

  <Accordion title="Use Different Keys per Environment" icon="layer-group">
    Create separate API keys for each environment to isolate security risks.

    ```
    Development → dev_key_xxx
    Staging     → stg_key_xxx
    Production  → prod_key_xxx
    ```

    This way, if a development key is compromised, your production environment remains secure.
  </Accordion>

  <Accordion title="Monitor API Key Usage" icon="chart-simple">
    Regularly check your API key usage in the dashboard:

    * Track request volume
    * Monitor for unusual patterns
    * Review error rates
    * Check which endpoints are being accessed

    Set up alerts for:

    * Unusually high request volume
    * Requests from unexpected IP addresses
    * High error rates
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="ban">
    **Problem**: Your request returns a 401 Unauthorized error.

    **Solutions**:

    * Verify your API key is correct
    * Check that the `x-api-key` header is included
    * Ensure no extra spaces or characters in the key
    * Verify the key hasn't been deleted or revoked

    ```javascript theme={null}
    // ✅ Correct
    headers: { 'x-api-key': 'your-api-key' }

    // ❌ Wrong - don't use "Bearer" prefix
    headers: { 'x-api-key': 'Bearer your-api-key' }

    // ❌ Wrong - incorrect header name
    headers: { 'Authorization': 'your-api-key' }
    ```
  </Accordion>

  <Accordion title="403 Forbidden" icon="lock">
    **Problem**: Your request returns a 403 Forbidden error.

    **Possible causes**:

    * API key doesn't have permission for this endpoint
    * Account has been suspended
    * Request from blocked IP address

    **Solution**: Contact support at [support@pods.finance](mailto:support@pods.finance)
  </Accordion>

  <Accordion title="API Key Not Working" icon="question">
    **Problem**: New API key doesn't work immediately.

    **Solution**: API keys may take up to 30 seconds to propagate. Wait a moment and try again.

    If the issue persists:

    1. Verify you copied the entire key
    2. Check for hidden characters or spaces
    3. Try generating a new key
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/getting-started/quickstart">
    Make your first API call
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore available endpoints
  </Card>

  <Card title="Yield Guides" icon="book-open" href="/guides/yield/check-protocol-info">
    Deposit, withdraw, and monitor positions
  </Card>

  <Card title="Swap Guides" icon="arrows-rotate" href="/guides/swaps/get-quote">
    Integrate token swaps into your app
  </Card>
</CardGroup>