# Authentication

All Cubit API requests require authentication via API key.

## Getting Your API Key

1. **Create an account** at [cubit.maidenlabs.tools](https://cubit.maidenlabs.tools)
2. **Navigate to Dashboard** -> [cubit.maidenlabs.tools/dashboard](https://cubit.maidenlabs.tools/dashboard)
3. **Click "Create API Key"** to generate your key
4. **Copy and store securely** - the key is shown only once

Your API key will look like: `cubit_abc123xyz789...`

## Using Your API Key

### With the Python SDK (Recommended)

```python
from cubit import CubitClient

client = CubitClient("cubit_your_api_key")

# All subsequent calls are authenticated
job = client.get_job("15-1252.00")
```

### With HTTP Requests

Include your API key in the `Authorization` header as a Bearer token:

```bash
curl -H "Authorization: Bearer cubit_your_api_key" \
  https://api.maidenlabs.tools/jobs/15-1252.00
```

### With JavaScript/Fetch

```javascript
const response = await fetch('https://api.maidenlabs.tools/jobs/15-1252.00', {
  headers: {
    'Authorization': 'Bearer cubit_your_api_key',
    'Content-Type': 'application/json'
  }
});
const job = await response.json();
```

## Check Your API Key Status

Use the `/me` endpoint to verify your key and check your current tier:

```python
from cubit import CubitClient

client = CubitClient("cubit_your_api_key")
info = client.me()

print(f"Tier: {info['tier']}")
print(f"Organization: {info['org_name']}")
print(f"Daily Limit: {info['rate_limit']['daily_limit']}")
print(f"Remaining: {info['rate_limit']['remaining']}")
```

**Response:**

```json
{
  "tier": "professional",
  "org_name": "Acme EdTech",
  "rate_limit": {
    "daily_limit": 1000,
    "remaining": 847,
    "resets_at": "2026-01-24T00:00:00Z"
  },
  "permissions": {
    "semantic_search": true,
    "task_data": true,
    "regional_data": true,
    "custom_scoring": false,
    "batch_operations": false
  }
}
```

## API Key Security

{% hint style="danger" %}
**Never expose your API key in client-side code.** Your key should only be used in server-side applications.
{% endhint %}

### Best Practices

| Do                             | Don't                               |
| ------------------------------ | ----------------------------------- |
| Store in environment variables | Hardcode in source files            |
| Use server-side only           | Include in frontend JavaScript      |
| Rotate periodically            | Share across teams without tracking |
| Use separate keys for dev/prod | Use production keys in development  |

### Environment Variables

```bash
# .env file (never commit this!)
CUBIT_API_KEY=cubit_your_api_key
```

```python
import os
from cubit import CubitClient

client = CubitClient(os.environ["CUBIT_API_KEY"])
```

## Rotating Your API Key

If your key is compromised or you want to rotate for security:

1. Go to [cubit.maidenlabs.tools/dashboard](https://cubit.maidenlabs.tools/dashboard)
2. Click **"Rotate Key"**
3. Your old key is immediately invalidated
4. Copy your new key and update your applications

{% hint style="warning" %}
Key rotation is immediate. Update all your services before rotating to avoid downtime.
{% endhint %}

## Troubleshooting

### 401 Unauthorized

```json
{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or expired."
}
```

**Causes:**

* Typo in the API key
* Key was rotated/revoked
* Missing `Bearer` prefix in header

### 403 Forbidden

```json
{
  "error": "insufficient_tier",
  "message": "Requires: ['professional', 'enterprise']. Your tier: sandbox",
  "upgrade_url": "https://cubit.maidenlabs.tools/pricing"
}
```

**Cause:** You're accessing a feature not available on your tier. See [Tier Access Levels](/core-concepts/tiers.md).

### 429 Rate Limited

```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please wait or upgrade your plan."
}
```

**Cause:** You've exceeded your daily request quota. See [Rate Limits](/resources/rate-limits.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maidenlabs.tools/getting-started/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.