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

# Authentication

> Learn how to authenticate with the Qwairy API using Bearer tokens

All API requests require a Bearer token in the `Authorization` header. Tokens are scoped to your team and provide access to all brands within your account.

## Getting Your API Token

<Steps>
  <Step title="Navigate to API Access">
    Go to your [Team Management > API Access](https://qwairy.co/dashboard/team/api).
  </Step>

  <Step title="Create a new token">
    Click **Create API Token** and give it a descriptive name (e.g., "Marketing Dashboard", "Data Warehouse").
  </Step>

  <Step title="Copy and store securely">
    Your token will be shown **only once**. Copy it immediately and store it securely.
  </Step>
</Steps>

<Warning>
  **Keep your tokens secure!** Never commit tokens to version control or share them publicly. If a token is compromised, revoke it immediately from **Team Management > API Access**.
</Warning>

## Using Your Token

Include the token in the `Authorization` header with the `Bearer` prefix:

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands" \
  -H "Authorization: Bearer qw-api-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Token Format

All Qwairy API tokens follow this format:

```
qw-api-[32 hexadecimal characters]
```

Example: `qw-api-a1b2c3d4e5f6789012345678abcdef01`

## Authentication Errors

Authentication failures return HTTP `401` with a flat body — `error` is a short status label and `message` explains the failure:

| Condition                                                          | `message`                                                                        |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Missing or malformed `Authorization` header (not `Bearer <token>`) | `Missing or invalid Authorization header. Use: Authorization: Bearer qw-api-xxx` |
| Invalid or revoked token, or plan below Growth                     | `Invalid API token or insufficient subscription plan (Growth+ required)`         |

### Example Error Response

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qw-api-xxx"
}
```

See [Error Codes](/api-reference/errors) for the full list of error shapes, including the nested shape used by resource (validation and not-found) errors.

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="key">
    Store tokens in environment variables, not in code.

    ```bash theme={null}
    export QWAIRY_API_TOKEN="qw-api-xxx"
    ```
  </Card>

  <Card title="Create Descriptive Names" icon="tag">
    Name tokens by their purpose for easy management.
  </Card>

  <Card title="Rotate Regularly" icon="rotate">
    Delete and recreate tokens periodically for security.
  </Card>

  <Card title="Use Separate Tokens" icon="layer-group">
    Create different tokens for different integrations.
  </Card>
</CardGroup>

## Managing Tokens

You can manage your API tokens from [Team Management > API Access](https://qwairy.co/dashboard/team/api):

* **View tokens**: See all active tokens with their last usage date
* **Delete tokens**: Revoke access immediately by deleting a token
* **Create new tokens**: Generate new tokens as needed

<Note>
  There's no limit to the number of tokens you can create, but we recommend keeping only the tokens you actively use.
</Note>