API permissions

Permissions control what an API key or MCP connection can do within its organization. Choose only the operations your application or assistant needs.

How access is determined

Access method	What determines access
Dashboard	Your membership role in the selected organization.
REST API	The permissions granted to the API key used for the request.
MCP	The permissions approved for that OAuth connection. You can approve only permissions allowed by your organization role.

Most resource areas have separate read, create/update, and delete permissions. Images also have distinct create and store permissions; usage has read access only. Granting one permission does not grant the others, and permissions do not override plan restrictions.

Permission reference

Use these exact strings in API key permissions arrays. MCP OAuth uses the same strings for supported scopes, but does not expose API key management.

Permission	Allows
`images:create`	Create images from HTML/CSS, URLs, templates, or batches; sign create-and-render URLs.
`images:read`	List images and read their details.
`images:delete`	Delete images.
`images:store`	Use authenticated store endpoints to render and store images in their configured storage destination.
`templates:read`	List/read templates and their versions.
`templates:create_update`	Create and update templates.
`templates:delete`	Delete templates.
`proxies:read`	List/get proxy configurations, including usernames but never passwords.
`proxies:create_update`	Create/update proxies, credentials, and enabled state.
`proxies:delete`	Delete proxies.
`storage_destinations:read`	List/get storage configurations and test results without secret access keys.
`storage_destinations:create_update`	Create/update storage destinations and credentials; obtain the AWS external ID.
`storage_destinations:delete`	Delete storage destination configurations.
`og_configs:read`	List/get OG configurations.
`og_configs:create_update`	Create/update OG configurations.
`og_configs:delete`	Delete OG configurations.
`usage:read`	Read REST usage; call MCP `check_usage` and `get_max_batch_size`.
`api_keys:read`	List/get API key metadata without secrets. REST only.
`api_keys:create_update`	Create/update API keys within the caller’s authority. REST only.
`api_keys:delete`	Disable API keys through DELETE, within the caller’s authority. REST only.

The MCP tools reference lists which operations have tools. A supported OAuth scope does not necessarily have a dedicated tool; for example, there are no image or template deletion tools.

Using resources versus managing them

Creating an image from a known template ID uses images:create. Discovering templates first requires templates:read. Updating the template requires templates:create_update.

Likewise, configuring a proxy or storage destination is a management operation. Passing an existing proxy_id or storage_destination_id to image creation does not require permission to edit that resource. Resource ownership, enabled state, and plan eligibility still apply. A separate authenticated PUT /v1/store/{id} request requires images:store.

Reading an already hosted public image URL does not require images:read.

Granting permissions

A key with api_keys:create_update can create keys only with permissions it can itself grant. To update an existing key, the caller must be able to grant both its existing permissions and the requested replacement permissions. This check also applies to disabling or re-enabling a key. Disabling through DELETE requires authority over the target key’s existing permissions.

For example, a key with api_keys:create_update and images:create can create another image-creation key. It cannot grant templates:delete, and it cannot edit a key that already has that permission.

Current and future permissions

An explicit permission list grants only those operations. Even selecting every current permission does not grant permissions introduced later.

For API keys, all_future_permissions: true opts into all current and future permissions. Only a caller with that authority can grant it. Dashboard Owners have this authority; Admins have the current permission set. MCP cannot grant all future permissions or manage API keys.

The API requires a permissions array. Use [] with all_future_permissions: true. With all_future_permissions: false, an empty array grants no product operations.

Organization roles

Owners can grant all current and future permissions. Admins can grant current permissions, including management operations, but cannot manage keys with all-future access. Users can operate on images and templates, view usage, and read organization resource configurations and API key metadata; they cannot manage keys or change proxy, storage, or OG configurations.

See organization settings for membership and billing permissions. API keys belong to the organization; their grants are distinct from the dashboard role of the person using the API.

Existing keys and connections

The original API key defaults include image creation/read/delete/store, template read/create-update/delete, and usage read. They do not include management-resource grants.

The original MCP defaults include image creation/read/store, template read/create-update, proxy and storage listing, and usage read. Existing connections do not automatically gain new management permissions. Complete a new MCP authorization to approve additional access. Refreshing an existing token does not expand its permissions.

Permission errors

A REST request with valid credentials but insufficient permissions returns 403 with a message identifying the required permission. MCP returns a tool error and does not execute the denied operation. Add the appropriate key grant or reauthorize the MCP connection before retrying. If the message identifies a plan restriction, changing permissions alone will not resolve it.

Need help?

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