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

# Authentication

> Get your Whisul API key, pass it in the Authorization: Bearer header on every request, and follow best practices to keep it secure.

Every request to the Whisul API must include a valid API key. Whisul uses Bearer token authentication — you pass your key in the `Authorization` header of each request. This page explains how to get your key, how to use it, and what to do if authentication fails.

## Get your API key

1. Go to [whisul.com](https://whisul.com) and sign up for an account.
2. After logging in, open your dashboard.
3. Locate the **API Keys** section and copy your key.

<Warning>
  Your API key is a secret. Do not share it publicly, include it in client-side code, or commit it to version control. If your key is compromised, regenerate it from your dashboard immediately.
</Warning>

## Pass your key in requests

Include your API key in the `Authorization` header using the `Bearer` scheme on every API request:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Here is a complete example using curl:

```bash theme={null}
curl --request POST \
  --url https://whisul.com/api/generate \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"prompt": "a relaxing lo-fi beat"}'
```

Replace `YOUR_API_KEY` with the key you copied from your dashboard.

## Handle 401 Unauthorized errors

If your API key is missing, malformed, or invalid, the API returns a `401 Unauthorized` response. Common causes:

* You forgot to include the `Authorization` header
* The header value is not formatted as `Bearer YOUR_API_KEY`
* Your key was regenerated and the old one is no longer valid

To fix a `401` error, verify that:

1. The `Authorization` header is present in your request
2. The value starts with `Bearer ` followed by your key (note the space after `Bearer`)
3. The key matches the one currently shown in your Whisul dashboard

## Security best practices

<Warning>
  Never hardcode your API key in source code that you commit to a repository. Use environment variables or a secrets manager instead.
</Warning>

Follow these practices to keep your key secure:

* **Use environment variables.** Store your key in an environment variable such as `WHISUL_API_KEY` and read it at runtime.
* **Add your key file to `.gitignore`.** If you use a `.env` file locally, make sure it is listed in `.gitignore` before you commit.
* **Rotate your key if exposed.** If you accidentally publish your key, go to your Whisul dashboard and regenerate it immediately. The old key will stop working as soon as you do.
* **Restrict usage to server-side code.** Never expose your API key in front-end JavaScript or mobile apps where users can inspect it.

<Tip>
  Most languages support reading environment variables natively. For example, in a shell environment you can set `export WHISUL_API_KEY=your_key_here` and then reference it as `$WHISUL_API_KEY` in curl commands.
</Tip>