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

# Authentication

> Authenticate with the Vintl API using an API key in the X-API-Key header.

Every `/v1/*` endpoint requires an API key in the `X-API-Key` header.

## Get your key

Sign up at [app.vintl.io](https://app.vintl.io/signup). Your key is shown once at creation — copy it immediately. We store a SHA-256 hash only (the Stripe model — if you lose the key, generate a new one).

```
vntl_live_sk_7f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c
```

The `vntl_live_` prefix identifies it as a Vintl production key.

## Send your key

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -H "X-API-Key: $VINTL_API_KEY" \
    "https://api.vintl.io/v1/ping"
  ```

  ```python Python theme={"dark"}
  import os, requests

  resp = requests.get(
      "https://api.vintl.io/v1/ping",
      headers={"X-API-Key": os.environ["VINTL_API_KEY"]}
  )
  print(resp.json())
  ```

  ```typescript TypeScript theme={"dark"}
  const resp = await fetch("https://api.vintl.io/v1/ping", {
    headers: { "X-API-Key": process.env.VINTL_API_KEY! },
  });
  console.log(await resp.json());
  ```
</CodeGroup>

`/v1/ping` validates your key and returns plan info:

```json theme={"dark"}
{
  "status": "ok",
  "plan": "indie",
  "daily_limit": 10000,
  "daily_used": 42
}
```

## Errors

Missing header returns `401`:

```json theme={"dark"}
{
  "type": "https://vintl.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "missing X-API-Key header",
  "instance": "/v1/ping",
  "request_id": "req_..."
}
```

Invalid or revoked key also returns `401` with `"detail": "invalid API key"`. See [Errors](/essentials/errors) for the full reference.

<Warning>
  Never commit your API key to version control. Use environment variables or a secrets manager.
</Warning>

## Best practices

| Do                                      | Don't                           |
| --------------------------------------- | ------------------------------- |
| `export VINTL_API_KEY=vntl_live_sk_...` | Hardcode the key in source      |
| `os.environ["VINTL_API_KEY"]`           | Pass the key as a URL parameter |
| Add `.env` to `.gitignore`              | Commit `.env` files             |
| Rotate keys quarterly in the dashboard  | Share keys across environments  |

## Public endpoints

These don't require authentication:

| Endpoint       | Purpose                                         |
| -------------- | ----------------------------------------------- |
| `GET /healthz` | Liveness — is the server running?               |
| `GET /readyz`  | Readiness — are the database and cache healthy? |