Authentication

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

Open the Dealership Manager

In the Hrizn Dashboard, navigate to the dealership you want to integrate with.

Go to the API tab

Click the API tab in the dealership settings.

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

Copy the key

The raw key is displayed once. Copy and store it securely.

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.

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:

For a detailed breakdown of which endpoints each scope unlocks, see the Scopes Reference.

Using Your API Key

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

curl https://api.app.hrizn.io/v1/public/site \
  -H "X-API-Key: hzk_your_key_here"

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();

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"]

$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));

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:

Full Access
Read Only
Content Generation
Inventory Only

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

ideaclouds:read content:read inventory:read site:readRead data without creating or modifying anything. Ideal for dashboards and reporting tools.

ideaclouds:read ideaclouds:write content:read content:write compliance:write content_tools:write site:readFull content creation workflow without inventory access. Use for CMS integrations that only need to create articles.

inventory:read inventory:write site:readVehicle data and description generation only. Use for inventory management integrations.

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

Getting Started

Concepts

Guides

Scopes

Getting an API Key

Scope Access Model

Using Your API Key

Key Format

Key Security

Scope Presets

Error Responses

​Getting an API Key

​Scope Access Model

​Using Your API Key

​Key Format

​Key Security

​Scope Presets

​Error Responses

Getting an API Key

Scope Access Model

Using Your API Key

Key Format

Key Security

Scope Presets

Error Responses