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

# Authentication

> How to authenticate your API requests

## API Keys

All Mavera API requests require authentication using an API key. API keys are passed via the `Authorization` header as a Bearer token.

```bash theme={"dark"}
Authorization: Bearer mvra_live_your_key_here
```

## Creating an API Key

<Steps>
  <Step title="Navigate to Developer Settings">
    Go to [app.mavera.io/settings/developer](https://app.mavera.io/settings/developer)
  </Step>

  <Step title="Click Create API Key">
    Give your key a descriptive name (e.g., "Production Server", "Development")
  </Step>

  <Step title="Copy Your Key">
    Copy the key immediately. For security, it won't be displayed again.
  </Step>
</Steps>

## Key Format

Mavera API keys follow this format:

```
mvra_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

* **Prefix**: `mvra_live_` indicates a live production key
* **Length**: 32+ characters total

## Using Your Key

<CodeGroup>
  ```python Python theme={"dark"}
  from openai import OpenAI

  client = OpenAI(
      api_key="mvra_live_your_key_here",
      base_url="https://app.mavera.io/api/v1",
  )
  ```

  ```javascript JavaScript theme={"dark"}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "mvra_live_your_key_here",
    baseURL: "https://app.mavera.io/api/v1",
  });
  ```

  ```bash cURL theme={"dark"}
  curl https://app.mavera.io/api/v1/personas \
    -H "Authorization: Bearer mvra_live_your_key_here"
  ```

  ```go Go theme={"dark"}
  import "github.com/sashabaranov/go-openai"

  config := openai.DefaultConfig("mvra_live_your_key_here")
  config.BaseURL = "https://app.mavera.io/api/v1"
  client := openai.NewClientWithConfig(config)
  ```
</CodeGroup>

## Security Best Practices

<Warning>
  Never expose your API key in client-side code, public repositories, or logs.
</Warning>

### Do's

<Check>Store keys in environment variables</Check>
<Check>Use secrets management (AWS Secrets Manager, HashiCorp Vault, etc.)</Check>
<Check>Rotate keys periodically</Check>
<Check>Use different keys for development and production</Check>
<Check>Revoke compromised keys immediately</Check>

### Don'ts

<Cross>Commit keys to version control</Cross>
<Cross>Include keys in client-side JavaScript</Cross>
<Cross>Share keys via email or chat</Cross>
<Cross>Log API keys in application logs</Cross>

## Environment Variables

Store your API key in an environment variable:

```bash .env theme={"dark"}
MAVERA_API_KEY=mvra_live_your_key_here
```

Then access it in your code:

<CodeGroup>
  ```python Python theme={"dark"}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["MAVERA_API_KEY"],
      base_url="https://app.mavera.io/api/v1",
  )
  ```

  ```javascript JavaScript theme={"dark"}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.MAVERA_API_KEY,
    baseURL: "https://app.mavera.io/api/v1",
  });
  ```
</CodeGroup>

## Key Management

### Viewing Keys

View all your API keys at [Settings > Developer](https://app.mavera.io/settings/developer). You'll see:

* Key name
* Creation date
* Last used date
* Partial key preview (last 4 characters)

### Revoking Keys

To revoke a key:

1. Go to [Settings > Developer](https://app.mavera.io/settings/developer)
2. Find the key you want to revoke
3. Click the delete/revoke button
4. Confirm the action

<Warning>
  Revoking a key is immediate and irreversible. All requests using that key will fail with a 401 error.
</Warning>

## Authentication Errors

| Status | Code              | Description                                |
| ------ | ----------------- | ------------------------------------------ |
| 401    | `missing_api_key` | No Authorization header provided           |
| 401    | `invalid_api_key` | Key format is invalid or key doesn't exist |
| 401    | `revoked_api_key` | Key has been revoked                       |
| 401    | `expired_api_key` | Key has expired (if expiration was set)    |

Example error response:

```json theme={"dark"}
{
  "error": {
    "message": "Invalid API key. Ensure your key starts with 'mvra_live_' and has not been revoked.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}
```

## Subscription Requirement

API keys are tied to your subscription. You must have an active subscription to use the API. If your subscription expires:

* Existing keys remain valid but will return 402 errors
* You cannot create new keys
* Renewing your subscription restores API access

## Testing Your API Key

Verify your key works before integrating. A simple `GET` to list personas returns 200 if the key is valid:

```bash theme={"dark"}
curl -s -o /dev/null -w "%{http_code}" https://app.mavera.io/api/v1/personas \
  -H "Authorization: Bearer mvra_live_your_key_here"
```

A `200` response means the key is valid. `401` means the key is missing, invalid, or revoked.

To see the response body:

```bash theme={"dark"}
curl -s https://app.mavera.io/api/v1/personas \
  -H "Authorization: Bearer mvra_live_your_key_here" | jq '.data | length'
```

If you see a number (e.g. `52`), the key works and you have access to personas. If you see `{"error":...}`, check the error message and [Authentication Errors](#authentication-errors).

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get your first API call working
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/guides/rate-limits">
    Understand request limits
  </Card>

  <Card title="Error Handling" icon="exclamation-triangle" href="/guides/errors">
    Handle 401 and other errors
  </Card>

  <Card title="Developer Settings" icon="key" href="https://app.mavera.io/settings/developer">
    Create and manage keys
  </Card>
</CardGroup>