Authorization

Control what your API keys can access using scopes.

Overview

Shablonix API keys support fine-grained permissions through scopes. When you create an API key, you can restrict it to only the operations it needs, following the principle of least privilege.

If no scopes are specified when creating a key, it will have access to all scopes by default. We recommend creating keys with only the scopes required for your use case.

Available Scopes

The following scopes control access to different API operations:

Scope	Description
`templates:read`	List and retrieve templates.
`templates:write`	Create, update, and delete templates.
`documents:generate`	Generate documents (PDF, PNG, HTML, DOCX) from templates.
`api-keys:read`	List and view API key metadata (keys are never shown in full).
`api-keys:write`	Create and revoke API keys.
`usage:read`	View usage statistics and billing information.

Creating Scoped Keys

When creating an API key via the dashboard or the API, specify the scopes you want to grant:

Via the API

			
				curl -X POST https://api.shablonix.com/v1/api-keys \
  -H "Authorization: Bearer tf_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Generation Only",
    "scopes": ["templates:read", "documents:generate"]
  }'

Via the Dashboard

1 Navigate to Settings → API Keys
2 Click Create New Key
3 Select the scopes you want to grant from the permissions checklist
4 Copy and securely store the generated key

Principle of Least Privilege

Only grant the scopes your application actually needs. For example, a service that only generates documents should use templates:read and documents:generate scopes only.

Error Responses

If your API key lacks a required scope for an endpoint, the API returns a 401 Unauthorized response with details about the missing permissions:

401 Insufficient Scopes json

			
				{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Insufficient permissions. Required scopes: templates:write",
  "missingScopes": ["templates:write"],
  "yourScopes": ["templates:read", "documents:generate"],
  "hint": "Create a new API key with the required scopes or request additional permissions."
}

Scope Errors vs Auth Errors

A scope error (missing permissions) returns the same 401 status code as an authentication error (invalid key). Check the missingScopes field in the response body to distinguish between the two.