API Tokens

API tokens authenticate workers and applications with a single Hatchet tenant. Use an unrestricted token for workers and applications that trigger or modify work. Use a read-only token for REST API integrations that inspect tenant data.

Create a token

Sign in as a tenant ADMIN or OWNER, then open Settings > API Tokens and select Create API Token. Enter a name, choose an expiration, and optionally enable Read-only. The checkbox is off by default.

Copy the generated token and store it securely. It is only displayed once. The tokens table's Access column shows whether each token is Read-only or Unrestricted.

When creating a token through the REST API with an admin or owner session, set readOnly: true in the create request to request read-only access. Omitting readOnly, or setting it to false, creates an unrestricted token. Token list responses include readOnly for each token. API tokens cannot authenticate token-creation requests.

Unrestricted tokens

Unrestricted tokens can use gRPC, including worker registration and task completion. They bypass tenant member role checks in the REST API, but cannot list, create, or revoke API tokens.

Existing tokens remain unrestricted. Tokens generated by the admin CLI and internal services also remain unrestricted.

Read-only tokens

A read-only token uses the same REST API permissions as the tenant VIEWER role. It can list and get runs, tasks, events, logs, workers, and workflows. It cannot trigger, cancel, replay, create, update, or delete those resources, or manage API tokens.

Permissions are based on the operation, not its HTTP method. A few tenant-scoped POST operations are allowed for viewers, including CEL debugging (V1CelDebug). Read-only tokens can call these operations too. User-account operations, such as updating a login, accepting an invite, or completing an OAuth callback, are unavailable to API tokens because they are not tenant-scoped.

Payloads remain visible, including task inputs and outputs, event payloads, and log payloads. The member-level Can view payloads setting does not apply to API tokens, including read-only tokens.

Every gRPC call made with a read-only token returns PermissionDenied, including worker registration and task completion. This restriction also applies to gRPC calls that only read data. Use the REST API for read-only access.

Worker configuration

Workers require an unrestricted token. Leave Read-only unchecked when creating a worker token, then configure it through HATCHET_CLIENT_TOKEN or the SDK's token option:

export HATCHET_CLIENT_TOKEN="<your-unrestricted-token>"

A worker configured with a read-only token cannot connect to the engine. See Troubleshooting Workers if authentication fails with PermissionDenied.

Change access or revoke a token

A token's access level cannot be edited. To change it, revoke the token and create a replacement with the desired Read-only setting. Update any applications using the token.

Only an admin or owner session can list, create, or revoke API tokens. This restriction applies even when the API token itself is unrestricted.