Scopes Overview

Scopes define exactly which endpoints an API key can access. When you create a key, you choose one or more scopes. Every request is checked against the key’s scopes before it reaches the handler. If the key lacks the required scope, the request is rejected with a 403 Forbidden response.

All available scopes

Scope	Description	Endpoints
`ideaclouds:read`	List and retrieve IdeaClouds, questions, and clusters	3
`ideaclouds:write`	Create IdeaClouds (single and batch)	2
`content:read`	List and retrieve content, HTML, components, and compliance reports	5
`content:write`	Create content and trigger generation	3
`content_intelligence:read`	List, view, and dismiss content intelligence recommendations	4
`content_intelligence:write`	Act on recommendations and bulk-dismiss	2
`compliance:write`	Trigger compliance checks on articles	1
`content_tools:write`	Generate SEO metadata, schemas, and social snippets	2
`inventory:read`	List vehicles, view descriptions, feeds, and stats	5
`inventory:write`	Trigger AI description generation (single and batch)	2
`site:read`	View site details, categories, brand voices, elements, and content types	5
`webhooks:read`	List webhook subscriptions and delivery logs	2
`webhooks:write`	Create, update, delete, and test webhook subscriptions	4
`social:read`	List connected social accounts, posts, and reviews	5
`social:write`	Create, schedule, update, delete, unpublish, and retry posts	5
`reviews:write`	Generate and publish replies to social reviews	2

How scope enforcement works

Every public API endpoint declares one or more required scopes. When a request arrives, the authorizer:

Validates the API key from the X-API-Key header
Loads the key’s assigned scopes from the database
Checks if the key has at least one of the endpoint’s required scopes
If the key lacks the required scope, the request is rejected before the handler runs

403 Forbidden response

When a key does not have the required scope, the API returns:

{
  "error": {
    "code": "forbidden",
    "message": "This API key requires one of the following scopes: content:write",
    "details": {
      "required_scopes": ["content:write"]
    }
  }
}

The required_scopes array in details tells you exactly which scope(s) you need. Add the scope to your API key in the Hrizn Dashboard, or create a new key with the correct scopes.

Presets

When creating an API key in the dashboard, you can use presets to quickly assign common scope combinations:

Preset	Scopes included
Full Access	All 16 scopes
Read Only	`ideaclouds:read`, `content:read`, `inventory:read`, `site:read`, `content_intelligence:read`
Content Generation	All read scopes + `ideaclouds:write`, `content:write`, `compliance:write`, `content_tools:write`, `content_intelligence:read`, `content_intelligence:write`
Inventory Only	`inventory:read`, `inventory:write`, `site:read`
Social Management	`social:read`, `social:write`, `reviews:write`

Endpoints that do not require a specific scope

The following endpoints require a valid API key but are accessible with any scope:

Method	Path	Description
`GET`	`/public/reference/scopes`	List all available scopes
`GET`	`/public/reference/content-types`	List all content types
`GET`	`/public/reference/component-types`	List all component types
`GET`	`/public/reference/webhook-events`	List all webhook event types
`GET`	`/public/reference/content-tools`	List all content tools
`GET`	`/public/reference/content-intelligence-types`	List all content intelligence types

The health check endpoint does not require an API key at all:

Method	Path	Description
`GET`	`/public/health`	Health check (no authentication)

Check your key’s scopes programmatically

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

const res = await fetch("https://api.app.hrizn.io/v1/public/reference/scopes", {
  headers: { "X-API-Key": "hzk_your_key_here" },
});
const data = await res.json();

import requests

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

$ch = curl_init("https://api.app.hrizn.io/v1/public/reference/scopes");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["X-API-Key: hzk_your_key_here"],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));

{
  "data": {
    "scopes": {
      "ideaclouds:read": "List and view IdeaClouds and questions",
      "ideaclouds:write": "Create IdeaClouds",
      "content:read": "List and view content, components, HTML",
      "content:write": "Create content, trigger generation",
      "compliance:write": "Trigger compliance checks",
      "content_tools:write": "Generate schemas, meta, social snippets",
      "inventory:read": "List and view inventory, descriptions, feeds",
      "inventory:write": "Trigger inventory description generation",
      "webhooks:read": "View webhook subscriptions and deliveries",
      "webhooks:write": "Create, update, delete webhook subscriptions",
      "site:read": "View site details, brand voices, elements, categories",
      "content_intelligence:read": "List and view content intelligence recommendations, dismiss recommendations",
      "content_intelligence:write": "Act on recommendations and bulk-dismiss",
      "social:read": "List connected social accounts, posts, and reviews (all platforms)",
      "social:write": "Create, schedule, update, delete, unpublish, and retry social posts",
      "reviews:write": "Generate and publish replies to social reviews"
    }
  }
}

Getting Started

Concepts

Guides

Scopes

All available scopes

How scope enforcement works

403 Forbidden response

Presets

Endpoints that do not require a specific scope

Check your key’s scopes programmatically

​All available scopes

​How scope enforcement works

​403 Forbidden response

​Presets

​Endpoints that do not require a specific scope

​Check your key’s scopes programmatically

All available scopes

How scope enforcement works

403 Forbidden response

Presets

Endpoints that do not require a specific scope

Check your key’s scopes programmatically