> ## 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.

# API Keys Management

> How to create, manage, and use API keys for secure access to Stanna data

## Overview

API keys provide secure, programmatic access to your Stanna workspace data. Each API key is tied to your specific workspace and allows access to all endpoints with the same permissions as your user account.

## Creating Your First API Key

When you first access Stanna, you'll need to create an API key to unlock programmatic access to your data:

1. **Automatic Prompt**: If you don't have any API keys, Stanna will automatically prompt you to create one when you first access the dashboard
2. **Manual Creation**: You can also create additional keys through the Settings page

### Step-by-Step Guide

<Steps>
  <Step title="Access Settings">
    Navigate to the **Settings** page in your Stanna dashboard
  </Step>

  <Step title="Go to API Keys">
    Click on the **API Keys** tab in the settings menu
  </Step>

  <Step title="Create New Key">
    Click the **Create New Key** button
  </Step>

  <Step title="Name Your Key">
    Enter a descriptive name for your API key (e.g., "Production Dashboard", "Analytics Script", "Mobile App")
  </Step>

  <Step title="Save Securely">
    Copy your new API key immediately and store it securely - you won't be able to see it again
  </Step>
</Steps>

## API Key Security

<Warning>
  API keys provide full access to your workspace data. Treat them like passwords and follow these security best practices.
</Warning>

### Best Practices

* **Never expose API keys in client-side code** - Only use them in server-side applications
* **Store keys securely** - Use environment variables or secure credential management systems
* **Use descriptive names** - Name your keys based on their intended use to track access
* **Rotate keys regularly** - Delete old keys and create new ones periodically
* **Limit key scope** - Create separate keys for different applications or environments

### What Not to Do

❌ **Don't** commit API keys to version control\
❌ **Don't** share API keys via email, chat, or other insecure channels\
❌ **Don't** use the same API key across multiple applications\
❌ **Don't** store API keys in browser localStorage for production apps

## Managing Existing API Keys

### Viewing Your Keys

In the **Settings → API Keys** section, you can view all your existing API keys with:

* **Key Name**: The descriptive name you assigned
* **Key Preview**: A masked version of the key (e.g., `sk-1234...abcd`)
* **Created Date**: When the key was created
* **Last Used**: When the key was last used (helps identify inactive keys)
* **Status**: Whether the key is active or inactive

### Deleting API Keys

<Warning>
  Deleting an API key is permanent and will immediately break any applications using that key.
</Warning>

To delete an API key:

1. Go to **Settings → API Keys**
2. Find the key you want to delete
3. Click the delete button (trash icon)
4. Confirm the deletion

Make sure to update any applications using the deleted key with a new API key.

## Using API Keys in Your Code

### Environment Variables (Recommended)

Store your API key in environment variables:

```bash theme={null}
# .env file
STANNA_API_KEY=sk-your-api-key-here
```

```javascript theme={null}
// JavaScript/Node.js
const apiKey = process.env.STANNA_API_KEY;

const response = await fetch('https://api.stanna.com/api/metrics/summary?workspaceId=yourworkspace', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});
```

### Python Example

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

api_key = os.getenv('STANNA_API_KEY')
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

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

### cURL Example

```bash theme={null}
curl -X GET "https://api.stanna.com/api/metrics/summary?workspaceId=yourworkspace" \
  -H "Authorization: Bearer $STANNA_API_KEY" \
  -H "Content-Type: application/json"
```

## Troubleshooting

### Common Issues

**401 Unauthorized Error**

* Check that your API key is correct and hasn't been deleted
* Ensure you're including the `sk-` prefix
* Verify you're using the correct header format

**403 Forbidden Error**

* Make sure you have access to the specified workspace
* Check that your API key belongs to the correct workspace

**API Key Not Working**

* Verify the key is active in your settings
* Try creating a new API key to test
* Check for extra spaces or characters when copying the key

### Getting Help

If you're still having issues with API keys:

1. Check the [API Reference](/api-reference/introduction) for authentication examples
2. Verify your requests match the expected format
3. Contact support if you continue to experience issues

## Rate Limits

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

* **Rate Limit**: 1000 requests per hour per API key
* **Burst Limit**: 100 requests per minute
* **Headers**: Rate limit information is included in response headers

If you need higher limits, please contact support to discuss your use case.