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

# Authentication

> Authenticate ReyGrid API requests with a Bearer API key.

## How it works

The API uses a **Bearer token**. The token is your ReyGrid API key, sent in the `Authorization` header of every authenticated request.

| Item | Value |
| - | - |
| Scheme | HTTP `bearer` (`bearerFormat: API-Key`) |
| Header | `Authorization: Bearer <API_KEY>` |
| Where | Request header only |

Every endpoint except `GET /ping` requires authentication.

<RequestExample>
  ```bash cURL theme={"system"}
  curl https://reygrid.com/api/v1/validate \
    -H "Authorization: Bearer $REYGRID_API_KEY"
  ```

  ```python Python theme={"system"}
  import os, httpx

  res = httpx.get(
      "https://reygrid.com/api/v1/validate",
      headers={"Authorization": f"Bearer {os.environ['REYGRID_API_KEY']}"},
  )
  print(res.json())
  ```

  ```javascript JavaScript theme={"system"}
  const res = await fetch("https://reygrid.com/api/v1/validate", {
    headers: { Authorization: `Bearer ${process.env.REYGRID_API_KEY}` },
  });
  console.log(await res.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "success": true,
    "valid": true,
    "usage": { "total": 1337, "quotaLimit": 5000 }
  }
  ```
</ResponseExample>

## Validate a key

`GET /validate` confirms a key works and returns `usage.total` and `usage.quotaLimit`. See the [reference](/api-reference/validate-api-key).

## Authentication errors

A missing or invalid key returns **401** with the flat `AuthErrorResponse` shape:

```json theme={"system"}
{
  "error": "Unauthorized",
  "code": "AUTH_REQUIRED"
}
```

<Warning>
  401 bodies are **not** wrapped like other errors (`{ "success": false, "error": { … } }`). Check the HTTP status first, then parse accordingly. See [Errors](/rest-api/errors).
</Warning>

## Security considerations

* Keep keys on the server. Don't ship them in browser or mobile code.
* Load keys from environment variables or a secrets manager. Don't commit them.
* Avoid logging the `Authorization` header.
* Always use HTTPS. The base URL is `https://reygrid.com/api/v1`.
* If you build per-user experiences, authenticate users in **your** backend and call ReyGrid from there. See [Persistent conversations](/rest-api/conversations).

<Info>
  The OpenAPI specification documents only the Bearer API key. It does not describe key creation, rotation, or scopes.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.