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

# Authentication

> Learn how to authenticate with the Viggle API

## Setup

<Steps>
  <Step title="Create an API key" icon="key">
    Go to your [Viggle Dashboard](https://portal.viggle.ai/keys) and create a key.
  </Step>

  <Step title="Add the header to every request" icon="lock">
    ```bash theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```
  </Step>
</Steps>

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://apis.viggle.ai/api/render" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d "character_id=char_xxx&scene_id=scene_xxx"
  ```

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

  response = requests.post("https://apis.viggle.ai/api/render",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      data={"character_id": "char_xxx", "scene_id": "scene_xxx"})
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const form = new URLSearchParams();
  form.append("character_id", "char_xxx");
  form.append("scene_id", "scene_xxx");

  const response = await fetch("https://apis.viggle.ai/api/render", {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}` },
    body: form
  });
  const data = await response.json();
  ```
</CodeGroup>

## Security

<Warning>
  **Keep your API key secure.** Never expose it in client-side code or public repositories. Use server-side applications only.
</Warning>

<AccordionGroup>
  <Accordion title="Use environment variables">
    ```bash theme={null}
    export VIGGLE_API_KEY="your-api-key-here"
    ```

    ```python theme={null}
    import os
    api_key = os.environ.get("VIGGLE_API_KEY")
    ```
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Periodically rotate your API keys, especially if you suspect compromise.
  </Accordion>

  <Accordion title="Use separate keys per environment">
    Different keys for development, staging, and production.
  </Accordion>
</AccordionGroup>

## Auth errors

If authentication fails, the API returns `401 Unauthorized`:

```json theme={null}
{
  "detail": "API key required. Use Authorization: Bearer sk-xxx"
}
```

<Card title="See all error codes" icon="shield" href="/error-codes">
  Full list of HTTP status codes, causes, and solutions
</Card>