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

# Authentication

> How to authenticate with the Avatcado API

# Authentication

All API requests (except `/health`) require a Bearer token in the `Authorization` header.

<Snippet file="auth-header.mdx" />

## API key format

Keys use the prefix `avat_live_` followed by a random string:

```
avat_live_a1b2c3d4e5f6g7h8i9j0
```

## Using the SDKs

Install the official SDK for your language:

```bash theme={null}
npm install @avatcado/node   # Node.js
pip install avatcado          # Python
```

Initialize the client with your API key. Both SDKs also read the `AVATCADO_API_KEY` environment variable as a fallback if no key is passed directly.

<CodeGroup>
  ```typescript @avatcado/node theme={null}
  import Avatcado from "@avatcado/node";

  // Pass the key directly
  const avatcado = new Avatcado("avat_live_your_api_key");

  // Or set AVATCADO_API_KEY in your environment and omit the argument
  const avatcado = new Avatcado();
  ```

  ```python Python theme={null}
  from avatcado import Avatcado

  # Pass the key directly
  avatcado = Avatcado("avat_live_your_api_key")

  # Or set AVATCADO_API_KEY in your environment and omit the argument
  avatcado = Avatcado()
  ```
</CodeGroup>

## Test keys

Test keys use the prefix `avat_test_` and enable [test mode](/test-mode). With a test key:

* No upstream VIES/HMRC calls are made
* No quota is consumed
* Rate limit headers are omitted
* Responses include `meta.mode: "test"`
* [Magic VAT numbers](/test-mode#magic-vat-numbers) return predictable scenarios

```
avat_test_a1b2c3d4e5f6g7h8i9j0
```

## How keys are stored

API keys are hashed with **SHA-256** before storage. Avatcado never stores your raw key. This means:

* If you lose your key, it cannot be recovered. You'll need to generate a new one
* Even if the database were compromised, your key cannot be reversed

## What happens without a valid key

| Scenario                  | Result                                       |
| ------------------------- | -------------------------------------------- |
| No `Authorization` header | `401` - [unauthorized](/errors/unauthorized) |
| Invalid or revoked key    | `401` - [unauthorized](/errors/unauthorized) |
| Wrong format (not Bearer) | `401` - [unauthorized](/errors/unauthorized) |

Every error response includes a `docs_url` pointing to the relevant error page.