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

# Authentication

> How to authenticate with the Hrizn Public API

The Hrizn Public API uses **API keys** for authentication. Each key is tied to a single dealership site, ensuring strict data isolation between tenants.

## Getting an API Key

<Steps>
  <Step title="Open the Dealership Manager">
    In the [Hrizn Dashboard](https://app.hrizn.io), navigate to the dealership you want to integrate with.
  </Step>

  <Step title="Go to the API tab">
    Click the **API** tab in the dealership settings.
  </Step>

  <Step title="Create a new key">
    Click **Create API Key**. Configure:

    * **Name** - A descriptive label (e.g. "DSRPTV Production")
    * **Scopes** - Which endpoints the key can access
    * **Rate Limit** - Requests per minute (10-500)
    * **Expiration** - Optional expiry date
  </Step>

  <Step title="Copy the key">
    The raw key is displayed **once**. Copy and store it securely.
  </Step>
</Steps>

<Danger>
  The raw API key is shown **only once** at creation time. It cannot be retrieved later — if you lose it, you'll need to create a new key. Copy it immediately and store it in a secrets manager or environment variable.
</Danger>

## Scope Access Model

API keys are granted specific scopes that control which endpoint groups they can access. Each scope maps to a set of related endpoints:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    APIKey["API Key"] --> Scopes["Assigned Scopes"]
    Scopes --> IC["ideaclouds:read/write"]
    Scopes --> CT["content:read/write"]
    Scopes --> INV["inventory:read/write"]
    Scopes --> WH["webhooks:read/write"]
    Scopes --> SITE["site:read"]
    Scopes --> COMP["compliance:write"]
    Scopes --> TOOLS["content_tools:write"]
    IC --> ICEndpoints["IdeaClouds endpoints"]
    CT --> CTEndpoints["Content endpoints"]
    INV --> INVEndpoints["Inventory endpoints"]
    WH --> WHEndpoints["Webhook endpoints"]
```

<Tip>
  For a detailed breakdown of which endpoints each scope unlocks, see the [Scopes Reference](/scopes/overview).
</Tip>

## Using Your API Key

Include the key in the `X-API-Key` header:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.app.hrizn.io/v1/public/site \
    -H "X-API-Key: hzk_your_key_here"
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.app.hrizn.io/v1/public/site", {
    headers: { "X-API-Key": process.env.HORIZN_API_KEY },
  });
  const { data } = await response.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.app.hrizn.io/v1/public/site",
      headers={"X-API-Key": "hzk_your_key_here"},
  )
  data = response.json()["data"]
  ```

  ```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
  $ch = curl_init("https://api.app.hrizn.io/v1/public/site");
  curl_setopt_array($ch, [
      CURLOPT_HTTPHEADER => ["X-API-Key: hzk_your_key_here"],
      CURLOPT_RETURNTRANSFER => true,
  ]);
  $data = json_decode(curl_exec($ch));
  ```
</CodeGroup>

## Key Format

API keys follow the format:

```
hzk_<64 hex characters>
```

Example: `hzk_a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890`

The first 12 characters (`hzk_a1b2c3d4`) are stored as the **key prefix** and visible in the dashboard for identification.

## Key Security

| Feature         | Detail                                                               |
| --------------- | -------------------------------------------------------------------- |
| **Storage**     | Keys are SHA-256 hashed before storage. Hrizn never stores raw keys. |
| **Display**     | The raw key is returned exactly once at creation time.               |
| **Revocation**  | Keys can be revoked instantly from the dashboard.                    |
| **Expiration**  | Keys can have optional expiry dates (30, 90, 180, 365 days).         |
| **Isolation**   | Each key is bound to a single dealership site.                       |
| **Rate Limits** | Each key has independent per-minute and per-day rate limits.         |

## Scope Presets

Use these presets when creating keys, or select individual scopes:

<Tabs>
  <Tab title="Full Access">
    All available scopes. Use for trusted, full-featured integrations.

    `ideaclouds:read` `ideaclouds:write` `content:read` `content:write` `compliance:write` `content_tools:write` `inventory:read` `inventory:write` `webhooks:read` `webhooks:write` `site:read`
  </Tab>

  <Tab title="Read Only">
    `ideaclouds:read` `content:read` `inventory:read` `site:read`

    Read data without creating or modifying anything. Ideal for dashboards and reporting tools.
  </Tab>

  <Tab title="Content Generation">
    `ideaclouds:read` `ideaclouds:write` `content:read` `content:write` `compliance:write` `content_tools:write` `site:read`

    Full content creation workflow without inventory access. Use for CMS integrations that only need to create articles.
  </Tab>

  <Tab title="Inventory Only">
    `inventory:read` `inventory:write` `site:read`

    Vehicle data and description generation only. Use for inventory management integrations.
  </Tab>
</Tabs>

## Error Responses

| HTTP Status | Error Code     | Meaning                                            |
| ----------- | -------------- | -------------------------------------------------- |
| `401`       | `unauthorized` | Missing or invalid API key                         |
| `401`       | `key_expired`  | API key has passed its expiration date             |
| `401`       | `key_revoked`  | API key has been explicitly revoked                |
| `403`       | `forbidden`    | API key lacks the required scope for this endpoint |