windmill-labs · hcourdent · Mar 10, 2026 · Mar 6, 2026 · Mar 6, 2026 · Mar 10, 2026
diff --git a/docs/core_concepts/15_authentification/index.mdx b/docs/core_concepts/15_authentification/index.mdx
@@ -14,6 +14,11 @@ Windmill provides flexible authentication options to ensure secure access to the
 		description="Find out about the roles within a Windmill instance and their respective permissions."
 		href="/docs/core_concepts/roles_and_permissions"
 	/>
+	<DocCard
+		title="User tokens"
+		description="Generate API tokens with granular scopes to control access to specific resources and actions."
+		href="/docs/core_concepts/user_tokens"
+	/>
 </div>
 
 ## Restricted domain authentication

diff --git a/docs/core_concepts/39_http_routing/index.mdx b/docs/core_concepts/39_http_routing/index.mdx
@@ -247,7 +247,7 @@ Windmill supports several ways to secure HTTP triggers:
 | Method           | Description                                                                                  |
 |------------------|----------------------------------------------------------------------------------------------|
 | **None**         | Open to anyone (use only in trusted environments)                                            |
-| **Windmill Auth**| Uses a Windmill-signed JWT token to ensure the requesting agent has read access to both the runnable and the trigger. The token must be provided either in the Authorization header as Bearer `<token>`, or via a cookie named `token`. You can generate this token from your user settings. |
+| **Windmill Auth**| Uses a Windmill-signed JWT token to ensure the requesting agent has read access to both the runnable and the trigger. The token must be provided either in the Authorization header as Bearer `<token>`, or via a cookie named `token`. You can generate this token from your user settings. When selecting this option, you can generate a token pre-scoped with `http_triggers:read` access to the route directly from the trigger configuration. See [user tokens](../59_user_tokens/index.mdx) for more details on scoped tokens. |
 | **API Key**      | Checks a header (e.g., `x-api-key`) for a valid key stored as a resource                     |
 | **Basic Auth**   | Uses HTTP Basic Authentication via a configured resource                                     |
 | **Signature Auth** | Verifies a signature using HMAC or third-party formats (Stripe, GitHub, etc.)               |

diff --git a/docs/core_concepts/4_webhooks/index.mdx b/docs/core_concepts/4_webhooks/index.mdx
@@ -98,7 +98,7 @@ You can generate tokens for your own account in the
 **Account Settings menu** in the app. Open it by
 clicking your username on the side menu, then select "Account settings".
 
-Labels are only used to allow users to easily distinguish keys.
+Labels are only used to allow users to easily distinguish keys. Tokens can also be created with [granular scopes](../59_user_tokens/index.mdx) to restrict access to specific resources and actions.
 
 :::caution
 

diff --git a/docs/core_concepts/59_user_tokens/create_token.png b/docs/core_concepts/59_user_tokens/create_token.png
diff --git a/docs/core_concepts/59_user_tokens/index.mdx b/docs/core_concepts/59_user_tokens/index.mdx
@@ -0,0 +1,136 @@
+---
+description: How do I create and manage API tokens in Windmill? Generate tokens with granular scopes to control access to specific resources and actions.
+---
+
+import DocCard from '@site/src/components/DocCard';
+
+# User tokens
+
+User tokens are used to authenticate API requests to Windmill. Every interaction with the Windmill API requires a `Bearer` token. Tokens can be scoped to restrict access to specific resources and actions, following the principle of least privilege.
+
+<div className="grid grid-cols-2 gap-6 mb-4">
+	<DocCard
+		title="Roles and permissions"
+		description="Control access and manage permissions within your instance and workspaces."
+		href="/docs/core_concepts/roles_and_permissions"
+	/>
+	<DocCard
+		title="Webhooks"
+		description="Trigger scripts and flows from webhooks."
+		href="/docs/core_concepts/webhooks"
+	/>
+</div>
+
+## Create a token
+
+You can generate tokens from the **Account settings** menu. Open it by clicking your username on the side menu, then select "Account settings".
+
+![Create a new token](./create_token.png 'Create a new token')
+
+1. Enter a **label** to identify the token (labels help distinguish tokens in the list).
+2. Optionally set an **expiration date**.
+3. Click **New token** to create a token with full access, or enable **Limit token permissions** to restrict the token to specific scopes.
+
+:::caution
+
+You can only see the token once, when it is created. Make sure to store it securely.
+
+:::
+
+## Token scopes
+
+By default, tokens inherit the full permissions of the user who created them. By enabling the **Limit token permissions** toggle, you can restrict a token to only the actions and resources it needs.
+
+![Scope selector](./scope_selector.png 'Scope selector')
+
+Selected scopes appear as badges at the top of the selector. Each domain (Jobs, Scripts, Flows, etc.) can be expanded to configure `Read`, `Write`, or `Run` permissions. Use the **Restrict paths** button to limit a scope to specific resource paths.
+
+### Scope format
+
+Scopes follow the format:
+
+```
+{domain}:{action}[:{resource_path}]
+```
+
+- **domain**: the resource category (e.g. `scripts`, `flows`, `jobs`, `resources`)
+- **action**: `read`, `write`, or `run` (for jobs)
+- **resource_path** (optional): restrict access to specific paths, with wildcard support
+
+Examples:
+
+| Scope | Description |
+| --- | --- |
+| `scripts:read` | Read access to all scripts |
+| `scripts:write:f/production/*` | Write access to scripts in the `f/production/` folder |
+| `jobs:run:scripts:u/admin/my_script` | Run a specific script |
+| `jobs:run:flows` | Run any flow |
+| `resources:read:u/user/*` | Read resources owned by `u/user/` |
+
+A `write` scope automatically includes `read` access for the same domain and resource.
+
+### Available scope domains
+
+All domains support `read` and `write` actions. The **Jobs** domain additionally supports `run:scripts` and `run:flows`.
+
+Domains with path restriction support: `scripts`, `flows`, `apps`, `raw_apps`, `resources`, `variables`, `schedules`, `folders`, `jobs` (for run), and all trigger types (`http_triggers`, `websocket_triggers`, `kafka_triggers`, `nats_triggers`, `mqtt_triggers`, `sqs_triggers`, `gcp_triggers`, `postgres_triggers`).
+
+Domains without path restriction: `users`, `groups`, `workspaces`, `audit`, `workers`, `settings`, `service_logs`, `configs`, `oauth`, `ai`, `agent_workers`, `drafts`, `favorites`, `inputs`, `job_helpers`, `openapi`, `capture`, `concurrency_groups`, `oidc`, `acls`, `indexer`, `teams`, `git_sync`.
+
+### Resource path patterns
+
+For scopes that support it, you can restrict access to specific resource paths using the **Restrict paths** button in the scope selector. Wildcards are supported:
+
+| Pattern | Matches |
+| --- | --- |
+| `u/admin/my_script` | Exact path only |
+| `u/admin/*` | All resources under `u/admin/` |
+| `f/production/*` | All resources in the `f/production/` folder |
+| (omitted) | All resources in the domain |
+
+Multiple paths can be combined with commas: `scripts:read:f/production/*,f/staging/*`.
+
+### HTTP triggers and tokens
+
+When calling an [HTTP trigger](../39_http_routing/index.mdx) with Windmill Auth, the token must have `http_triggers:read` access to the trigger path. For example, a scoped token calling an HTTP route at `my_route` needs `http_triggers:read:my_route`.
+
+When configuring an HTTP trigger with **Windmill Auth**, you can generate a pre-scoped token directly from the trigger configuration page.
+
+## Webhook-specific tokens
+
+[Webhooks](../4_webhooks/index.mdx) can generate tokens that are pre-scoped to only trigger a specific script or flow. These tokens cannot impersonate you for any other operation, making them safe to share publicly.
+
+## Using tokens
+
+### Bearer authentication
+
+Include the token in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer <TOKEN>" \
+  https://your-windmill-instance.com/api/w/<workspace>/jobs/run/p/<script_path>
+```
+
+### Query parameter
+
+Alternatively, pass the token as a query parameter:
+
+```
+https://your-windmill-instance.com/api/w/<workspace>/jobs/run/p/<script_path>?token=<TOKEN>
+```
+
+### From scripts
+
+Within Windmill scripts, an ephemeral token for the current job is available as the `WM_TOKEN` environment variable. It can be used to call the Windmill API directly, for example to fetch [variables](../2_variables_and_secrets/index.mdx) or [resources](../3_resources_and_types/index.mdx). The [TypeScript](../../advanced/2_clients/ts_client.mdx), [Python](../../advanced/2_clients/python_client.md), and [Rust](../../advanced/2_clients/rust_client.mdx) client libraries load it automatically, so you typically don't need to handle it yourself.
+
+## Managing tokens
+
+From the Account settings page, you can view all your tokens with their labels, scopes, and expiration dates. Tokens can be revoked at any time by deleting them from the list.
+
+## CLI token creation
+
+You can also create tokens using the [Windmill CLI](../../advanced/3_cli/user.md):
+
+```bash
+wmill user create-token
+```
diff --git a/docs/core_concepts/59_user_tokens/scope_selector.png b/docs/core_concepts/59_user_tokens/scope_selector.png
diff --git a/docs/core_concepts/index.mdx b/docs/core_concepts/index.mdx
@@ -151,6 +151,11 @@ On top of its editors to build endpoints, flows, [low-code apps](../apps/0_app_e
 		description="Windmill provides flexible authentication options to ensure secure access to the platform."
 		href="/docs/core_concepts/authentification"
 	/>
+	<DocCard
+		title="User tokens"
+		description="Generate API tokens with granular scopes to control access to specific resources and actions."
+		href="/docs/core_concepts/user_tokens"
+	/>
 	<DocCard
 		title="Error handling"
 		description="There are 5 ways to do error handling in Windmill."

diff --git a/sidebars.js b/sidebars.js
@@ -391,6 +391,7 @@ const sidebars = {
 				'core_concepts/data_pipelines/index',
 				'core_concepts/roles_and_permissions/index',
 				'core_concepts/authentification/index',
+				'core_concepts/user_tokens/index',
 				'core_concepts/error_handling/index',
 				'core_concepts/jobs/index',
 				'core_concepts/monitor_past_and_future_runs/index',
@@ -958,7 +959,11 @@ const sidebars = {
 						type: 'doc',
 						id: 'advanced/self_host/index'
 					},
-					items: ['advanced/instance_settings/index', 'core_concepts/infrastructure_as_code/index', 'advanced/self_host/aws_eks_ecs']
+					items: [
+						'advanced/instance_settings/index',
+						'core_concepts/infrastructure_as_code/index',
+						'advanced/self_host/aws_eks_ecs'
+					]
 				},
 				{
 					type: 'category',