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

# Authentication

> BizyAir API authentication: obtain API Key, use Authorization Bearer header, common request headers, and security best practices.

## Obtaining an API Key

You need to obtain an API Key before calling the API:

1. Log in to [bizyair.ai](https://bizyair.ai)
2. Go to **API Keys**
3. Click **Create New Key** and enter an alias (e.g., `production` / `dev-local`)
4. Copy the generated Key (click the button on the left of the key to reveal it in full; click the key to copy it to the clipboard)

<Warning>
  An API Key is the sole credential for your account. If leaked, others can drain your account balance. Never commit it to Git, embed it in front-end code, or share it through public channels.
</Warning>

Request Authentication

All API requests must carry an `Authorization` field in the HTTP Header:

```http theme={null}
Authorization: Bearer $BIZYAIR_API_KEY
```

Example:

```bash theme={null}
curl -H "Authorization: Bearer $BIZYAIR_API_KEY" \
     "https://api.bizyair.ai/v1/user/info"
```

If the Key is missing or invalid, a 401 is returned:

```json theme={null}
{"code": "50503", "message": "Redis operation failed"}
```

## Common Request Headers

The following request headers apply to all invocation methods; some headers are used to control the invocation mode:

| Header                         | Required         | Description                                                                                     |
| ------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------- |
| `Authorization`                | ✅ Yes            | In `Bearer $BIZYAIR_API_KEY` format                                                             |
| `Content-Type`                 | ✅ Yes (POST/PUT) | Fixed as `application/json`                                                                     |
| `X-BizyAir-Task-Async`         | ❌ No             | Only effective for AI App APIs; standard model APIs are async by default                        |
| `X-BizyAir-Task-WebHook-Url`   | ❌ No             | Set a callback URL to enable WebHook mode                                                       |
| `X-BizyAir-Task-Authorization` | ❌ No             | Custom `Authorization` header for callback requests, used to verify the callback source         |
| `X-BizyAir-Task-*`             | ❌ No             | Any header with this prefix will be **passed through verbatim** to the WebHook callback request |

<Note>
  When both `X-BizyAir-Task-Async: enable` and `X-BizyAir-Task-WebHook-Url` are set, **WebHook mode takes precedence** and the async-query flag is ignored.
</Note>

## Security Best Practices

| Scenario             | Recommended                                                   | Forbidden                                   |
| -------------------- | ------------------------------------------------------------- | ------------------------------------------- |
| Server-side          | Store in environment variables / a secrets management service | ❌ Hard-code in source                       |
| Front-end (browser)  | Proxy through your own backend                                | ❌ Place directly in `fetch` request headers |
| Mobile               | Route through your own backend                                | ❌ Bundle into the app binary                |
| Open-source projects | Use a `.env` file + `.gitignore`                              | ❌ Commit `.env` to the repo                 |
| Team collaboration   | A separate Key per person, rotated regularly                  | ❌ Share the same Key                        |
| Suspected leak       | Disable it in Profile immediately and create a new Key        | ❌ Leave it as is                            |