Authentication and API keys

Every new HCTI organization automatically includes an API key, so you can start using the API without creating one yourself. You’ll find its API ID and secret API key in the API keys dashboard.

This key starts with the Basics permission set for everyday operations: creating and managing images, working with templates, and checking usage. It belongs to your organization and uses that organization’s resources and image credits.

You can expand its permissions to include Management API operations, or reduce them to just what your application needs. You can also create separate keys for different applications or environments, each with its own permissions—for example, an image-creation key for your website and a read-only key for monitoring usage. Organization Owners and Admins can manage these permissions within their authority.

To use your existing key, skip to authenticating a request. To create another key or understand the permission controls, follow the guide below.

Create a key in the dashboard

Open the API keys dashboard in the intended organization.
Select Create New Key. Organization Owners and Admins can create keys within their authority.
Give the key a name and optional description, such as Production renderer and the application that uses it.
Choose a permission preset, then adjust the selected permissions for your application.
Save the key and store the API ID and secret API key in your server’s environment or secret manager.

Simple view: read and write by area

By default, the form groups permissions into Read and Write for each area, such as Images, Templates, or Proxies. Choose a preset as a starting point, then adjust the groups your application needs.

Write includes deletion where the area supports it. For example, selecting Write for Proxies grants both create/update and delete permissions. Usage has only a Read permission.

Create an API key in the default simple view, with Read and Write permission groups for each resource area and the Basics preset selected. — The default view groups permissions by area. Click the screenshot to view it full size.

Permission presets

Preset	Included access
Basics	Original image, template, and usage operations, including image/template deletion and image storage.
Image Creator	`images:create` and `images:store`. Add `templates:read` if the application needs to discover templates, or `usage:read` to check usage.
Administrator	All current resource permissions, including key management. Does not automatically grant future permissions.
Read Only	Read permissions for images, templates, proxies, storage destinations, OG configurations, usage, and API key metadata.
Custom	Choose individual permissions for your application’s needs.

Advanced mode: choose individual actions

Turn on Advanced mode to see the granular permissions within each area. Read, Create/Update, and Delete are shown separately; Images also separates Create and Store. This lets you allow an application to create and update proxies without allowing it to delete them, for example.

Simple and advanced mode are two views of the same permission selection. Advanced mode lets you choose exactly which actions a key can perform.

Advanced mode in the API key form, showing separate Read, Create/Update, and Delete permissions, with Create and Store separated for Images. — Advanced mode exposes individual actions instead of grouping all writes together.

See what each permission allows

Expand an area’s details using the arrow next to its name. The details explain its read and write permissions. Expand Endpoints and required permissions to see which API endpoints use each permission, including the exact names to use in API requests.

Expanded OG Configs permission details showing read and write descriptions and the permissions required for each Open Graph configuration endpoint. — Each area includes descriptions and an endpoint-to-permission reference.

See the permission reference for the complete list. Plan and authentication requirements still apply to each endpoint.

Automatically grant future permissions

The Automatically grant future permissions toggle grants all current permissions and any new permissions added in the future. It does not just add future permissions to a limited selection. Leave it off to keep a key restricted to the permissions you explicitly choose.

Selecting the Administrator preset, or manually selecting every current permission, does not enable this setting. Those selections cover current permissions only.

In the Management API, this setting is called all_future_permissions. To enable it, send all_future_permissions: true with permissions: []. With all_future_permissions: false, the permissions array is the complete set of grants; an empty array grants no product operations.

Only callers with all-future authority can grant it. In the dashboard, Owners have that authority; Admins can grant current permissions but cannot enable all-future access or edit a key that has it. See API key management for request examples.

Authenticate a request

The image API and Management API both use HTTP Basic authentication:

Value	Use
API ID (`api_id`)	Basic Auth username. Some older examples call this the User ID.
API Key (`api_key`)	Basic Auth password; keep it secret.

With HCTI_API_ID and HCTI_API_KEY set in your server environment:

curl 'https://hcti.io/v1/image' \
  --user "$HCTI_API_ID:$HCTI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"html":"<h1>Hello from HCTI</h1>"}'

This request requires images:create. The same credentials can call the Management API if the key has the required management permissions.

Keep the secret out of browser code, public repositories, and chat messages. For browser-facing image generation, use signed create-and-render URLs. Their signing key needs images:create.

Edit permissions or disable a key

Open the key’s controls in the dashboard to edit its name, description, enabled state, or permissions. Disabled keys cannot authenticate requests and appear in Disabled Keys. Re-enable a key only if you intend to restore access for applications holding its existing credentials.

Owners can grant all current and future permissions. Admins can manage keys limited to current permissions, but cannot modify a key that grants all future permissions. API callers are likewise limited by the calling key’s authority. See granting permissions.

Replace credentials

To rotate a key, create a replacement with the required permissions, update your application’s stored API ID and API key, verify its requests, then disable the old key. Editing permissions does not change the secret.

When creating a key through the Management API, the secret is returned only in the creation response. List, get, and update responses contain metadata without the secret. See API key management for an automated rotation workflow.

Troubleshooting

401 Unauthorized: Check the API ID/secret pair and whether the key is enabled.
403 Forbidden: Read the missing permission or plan requirement in the response. Valid credentials do not imply access to every operation.
Wrong organization: Use credentials created in the organization that owns the resource.

MCP connections use OAuth authorization, so you do not need to copy API keys into an assistant.

Legacy API keys

All keys created before the introduction of granular permissions (September 2026) have the default permission set, unless their permissions have since been changed:

Area	Default permissions
Images	`images:create`, `images:read`, `images:delete`, `images:store`
Templates	`templates:read`, `templates:create_update`, `templates:delete`
Usage	`usage:read`

These eight permissions match the Basics preset and preserve the original image, template, and usage operations. Legacy keys do not automatically receive proxy, storage destination, OG configuration, or API key management permissions, and do not opt into all_future_permissions.

To use management operations, edit the key’s permissions in the dashboard or create a separate key with the required grants.

Need help?

Talk to a human. Please email us support@htmlcsstoimage.com with any questions and we’ll gladly help you get started.