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

# Authentication

> How to authenticate with the Stanna API

## Overview

The Stanna API uses API keys to authenticate requests. API keys can be created and managed through your dashboard settings page.

## Creating an API Key

<Steps>
  <Step title="Navigate to Settings">
    Go to your [Stanna Dashboard](https://app.gostanna.com) and click on **Settings** in the navigation
  </Step>

  <Step title="Find API Keys Section">
    Scroll down to the **API Keys** section at the bottom of the settings page
  </Step>

  <Step title="Create New Key">
    Click the **Create New Key** button and provide a descriptive name for your key
  </Step>

  <Step title="Copy Your Key">
    Copy the generated API key immediately - it won't be shown again for security reasons
  </Step>
</Steps>

## Using Your API Key

There are two ways to include your API key in requests:

### Method 1: Authorization Header (Recommended)

```bash theme={null}
curl -X GET "https://api.gostanna.com/api/clients?workspaceId=yourcompany.com" \
  -H "Authorization: Bearer sk-your-api-key-here"
```

### Method 2: X-API-Key Header

```bash theme={null}
curl -X GET "https://api.gostanna.com/api/clients?workspaceId=yourcompany.com" \
  -H "X-API-Key: sk-your-api-key-here"
```

## Example: Testing Your API Key

Here's a simple test to verify your API key is working:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.gostanna.com/api/metrics/summary?workspaceId=yourcompany.com" \
    -H "Authorization: Bearer sk-your-api-key-here"
  ```

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

  const response = await fetch('https://api.gostanna.com/api/metrics/summary?workspaceId=yourcompany.com', {
    headers: {
      'Authorization': 'Bearer sk-your-api-key-here'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

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

  headers = {
      'Authorization': 'Bearer sk-your-api-key-here'
  }

  response = requests.get(
      'https://api.gostanna.com/api/metrics/summary',
      params={'workspaceId': 'yourcompany.com'},
      headers=headers
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Security Best Practices

<Warning>
  Never expose your API keys in client-side code, public repositories, or insecure locations.
</Warning>

### Do's

* Store API keys in environment variables
* Use server-side code to make API calls
* Rotate keys regularly
* Create separate keys for different environments (dev, staging, prod)
* Delete unused keys promptly

### Don'ts

* Don't embed keys in client-side JavaScript
* Don't commit keys to version control
* Don't share keys via email or chat
* Don't use the same key across multiple applications

## Managing API Keys

You can manage your API keys through the settings page:

* **View active keys**: See all your active API keys and their last usage
* **Delete keys**: Remove keys that are no longer needed
* **Monitor usage**: Track when each key was last used

## Troubleshooting

### Common Error Messages

| Error                   | Cause                         | Solution                                                  |
| ----------------------- | ----------------------------- | --------------------------------------------------------- |
| `401 Unauthorized`      | Missing or invalid API key    | Check that your key is correct and properly formatted     |
| `403 Forbidden`         | Valid key but wrong workspace | Ensure the workspaceId matches your key's workspace       |
| `429 Too Many Requests` | Rate limit exceeded           | Reduce request frequency or implement exponential backoff |

### Testing Authentication

To test if your authentication is working correctly:

```bash theme={null}
curl -I -X GET "https://api.gostanna.com/api/metrics/summary?workspaceId=yourcompany.com" \
  -H "Authorization: Bearer sk-your-api-key-here"
```

A successful response will return `HTTP/2 200`. If you see `401` or `403`, check your API key and workspace ID.