Document namespace auth and worker registration

durable-workflow-ops · durable-workflow-ops · commit 8c8300eb1f54 · 2026-04-22T11:32:59.000Z
Document namespace auth worker registration
diff --git a/docs/polyglot/namespace-auth-workers.md b/docs/polyglot/namespace-auth-workers.md
@@ -0,0 +1,226 @@
+---
+sidebar_position: 4
+title: Namespace, Auth, And Worker Registration
+description: Reference for server namespace resolution, role-scoped authentication, and worker registration contracts.
+tags:
+  - server
+  - namespaces
+  - authentication
+  - worker-protocol
+keywords:
+  - Durable Workflow namespace auth
+  - role scoped server tokens
+  - worker registration contract
+  - X-Namespace
+---
+
+# Namespace, Auth, And Worker Registration
+
+Use this reference when provisioning a standalone server, issuing automation
+credentials, or implementing a worker runtime. The server has three separate
+contracts that must line up before work can flow:
+
+- the request names a namespace through `X-Namespace`, `?namespace=`, or the
+  server default namespace
+- the credential has the role required by the route family
+- workers register the same namespace, task queue, runtime, type keys, and
+  capacity that workflow starts and task polls use
+
+## Request Authority
+
+Durable Workflow treats namespace, auth role, and protocol version as request
+authority. Do not infer them from workflow ids, task ids, or display labels.
+
+| Request family | Required credential role | Required version header | Namespace source |
+| --- | --- | --- | --- |
+| Discovery `GET /api/cluster/info` | `worker`, `operator`, or `admin` | none | optional `X-Namespace` for context |
+| Namespace list/describe | `operator` or `admin` | `X-Durable-Workflow-Control-Plane-Version: 2` | route target or request context |
+| Namespace create/update/storage policy | `admin` | `X-Durable-Workflow-Control-Plane-Version: 2` | route target or request body |
+| Workflow, schedule, task queue, bridge adapter, worker visibility | `operator` or `admin` | `X-Durable-Workflow-Control-Plane-Version: 2` | `X-Namespace`, `?namespace=`, then default |
+| System passes and storage tests | `admin` | `X-Durable-Workflow-Control-Plane-Version: 2` | `X-Namespace`, `?namespace=`, then default |
+| Worker registration, polling, heartbeats, completion | `worker` | `X-Durable-Workflow-Protocol-Version: 1.0` | `X-Namespace`, `?namespace=`, then default |
+
+The server checks the route role before namespace existence on role-gated
+endpoints. A wrong-role token receives an auth failure instead of a namespace
+existence signal. After the role and version checks pass, namespace-scoped
+routes reject unknown namespaces with `reason: "namespace_not_found"`.
+
+## Auth Roles
+
+Token auth is the default production path:
+
+```bash
+DW_AUTH_DRIVER=token
+DW_WORKER_TOKEN=worker-secret
+DW_OPERATOR_TOKEN=operator-secret
+DW_ADMIN_TOKEN=admin-secret
+```
+
+If a deployment uses one shared `DW_AUTH_TOKEN`, that token effectively has all
+route permissions. Prefer role-scoped tokens for production so a worker process
+cannot mutate namespaces or run system maintenance passes.
+
+The same role split exists for signature auth:
+
+```bash
+DW_AUTH_DRIVER=signature
+DW_WORKER_SIGNATURE_KEY=worker-signature-secret
+DW_OPERATOR_SIGNATURE_KEY=operator-signature-secret
+DW_ADMIN_SIGNATURE_KEY=admin-signature-secret
+```
+
+`DW_AUTH_DRIVER=none` is for local development only. It removes the auth
+boundary from every route and should never be exposed outside a trusted local
+network.
+
+## Namespace Contract
+
+The bootstrap process seeds the default namespace. Set
+`DW_DEFAULT_NAMESPACE` when omitted namespace headers should resolve somewhere
+other than `default`:
+
+```bash
+DW_DEFAULT_NAMESPACE=default
+```
+
+Create every tenant or environment namespace before directing clients or
+workers at it:
+
+```bash
+curl -sS -X POST "$DURABLE_WORKFLOW_SERVER_URL/api/namespaces" \
+  -H "Authorization: Bearer $DW_ADMIN_TOKEN" \
+  -H "X-Durable-Workflow-Control-Plane-Version: 2" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "orders-prod",
+    "description": "production order workflows",
+    "retention_days": 90
+  }'
+```
+
+Namespace names are normalized to lowercase and may contain letters, numbers,
+dot, underscore, and dash. They are unique after normalization. For example,
+creating `Production` and then `production` is a conflict with
+`reason: "namespace_already_exists"`.
+
+A normal workflow start names the namespace with `X-Namespace`:
+
+```bash
+curl -sS -X POST "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \
+  -H "Authorization: Bearer $DW_OPERATOR_TOKEN" \
+  -H "X-Namespace: orders-prod" \
+  -H "X-Durable-Workflow-Control-Plane-Version: 2" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "workflow_type": "orders.fulfillment",
+    "workflow_id": "order-1001",
+    "task_queue": "orders",
+    "input": ["order-1001"]
+  }'
+```
+
+Control-plane reads, workflow commands, schedule operations, search-attribute
+operations, task-queue visibility, and worker visibility use that same
+namespace context. Namespace administration routes themselves are the
+exception: they target the namespace in the route or request body and do not
+require that namespace to already exist before create or describe can run.
+
+## Worker Registration Contract
+
+Every worker process must register before polling. Registration is namespaced,
+so the tuple `(namespace, worker_id)` identifies the worker record. The
+registered `task_queue` must match future poll requests for that worker id.
+
+```bash
+curl -sS -X POST "$DURABLE_WORKFLOW_SERVER_URL/api/worker/register" \
+  -H "Authorization: Bearer $DW_WORKER_TOKEN" \
+  -H "X-Namespace: orders-prod" \
+  -H "X-Durable-Workflow-Protocol-Version: 1.0" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "worker_id": "py-orders-1",
+    "task_queue": "orders",
+    "runtime": "python",
+    "sdk_version": "0.2.0",
+    "build_id": "orders-worker-2026-04-22",
+    "supported_workflow_types": ["orders.fulfillment"],
+    "workflow_definition_fingerprints": {
+      "orders.fulfillment": "sha256:definition-fingerprint"
+    },
+    "supported_activity_types": ["payments.capture"],
+    "max_concurrent_workflow_tasks": 10,
+    "max_concurrent_activity_tasks": 50
+  }'
+```
+
+| Field | Required | Contract |
+| --- | --- | --- |
+| `worker_id` | no | Stable process identity. The server generates one when omitted, but long-running runtimes should set it for logs and task queue diagnostics. |
+| `task_queue` | yes | Queue this worker polls. Poll requests for a different queue fail with `reason: "task_queue_mismatch"`. |
+| `runtime` | yes | One of `php`, `python`, `typescript`, `go`, or `java`. |
+| `sdk_version` | no | Runtime SDK version shown in worker visibility and diagnostics. |
+| `build_id` | no | Deploy/build identity used by task queue build-id visibility. |
+| `supported_workflow_types` | no | Workflow type keys this worker can replay. Empty means no workflow-type filter. |
+| `workflow_definition_fingerprints` | no | Per-workflow deterministic definition fingerprints. Active re-registration with a changed fingerprint is rejected. |
+| `supported_activity_types` | no | Activity type keys this worker can execute. Empty means no activity-type filter. |
+| `max_concurrent_workflow_tasks` | no | Advertised local workflow-task slots. Defaults to `100`; minimum `1`. |
+| `max_concurrent_activity_tasks` | no | Advertised local activity-task slots. Defaults to `100`; minimum `1`. |
+
+Active re-registration with the same worker id is allowed when the advertised
+definition fingerprints are unchanged. If a running worker changes workflow
+code for an already advertised type, it must restart with a new `worker_id`;
+otherwise registration fails with `reason: "workflow_definition_changed"`.
+
+## Polling And Visibility
+
+Worker poll requests must use the same namespace, worker id, and task queue
+that registration used:
+
+```bash
+curl -sS -X POST "$DURABLE_WORKFLOW_SERVER_URL/api/worker/workflow-tasks/poll" \
+  -H "Authorization: Bearer $DW_WORKER_TOKEN" \
+  -H "X-Namespace: orders-prod" \
+  -H "X-Durable-Workflow-Protocol-Version: 1.0" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "worker_id": "py-orders-1",
+    "task_queue": "orders",
+    "timeout_seconds": 30
+  }'
+```
+
+Operators can inspect the same registration state through control-plane
+visibility:
+
+```bash
+curl -sS "$DURABLE_WORKFLOW_SERVER_URL/api/task-queues/orders" \
+  -H "Authorization: Bearer $DW_OPERATOR_TOKEN" \
+  -H "X-Namespace: orders-prod" \
+  -H "X-Durable-Workflow-Control-Plane-Version: 2" | jq '.pollers, .admission'
+```
+
+Task queue visibility is the first place to check when workers receive no
+tasks. It distinguishes missing workers from queue mismatches, unsupported
+workflow/activity type filters, saturated worker slots, server active-lease
+caps, dispatch-rate caps, and query-task backpressure.
+
+## Error Surface
+
+Automation should branch on named reasons rather than prose messages.
+
+| Reason | Where | Meaning | Operator action |
+| --- | --- | --- | --- |
+| `missing_control_plane_version` | control-plane route | The request omitted `X-Durable-Workflow-Control-Plane-Version: 2`. | Add the version header or upgrade the client profile. |
+| `missing_protocol_version` | worker route | The request omitted `X-Durable-Workflow-Protocol-Version: 1.0`. | Fix the worker client or SDK version negotiation. |
+| `namespace_not_found` | namespace-scoped route | The namespace from `X-Namespace`, query string, or server default does not exist. | Create the namespace or correct the client namespace. |
+| `namespace_already_exists` | `POST /api/namespaces` | A normalized namespace name already exists. | Reuse it or choose a distinct name. |
+| `task_queue_mismatch` | worker poll route | A worker id registered for one queue attempted to poll another. | Restart with a new worker id or poll the registered queue. |
+| `workflow_definition_changed` | `POST /api/worker/register` | Active worker id tried to advertise changed workflow fingerprints. | Restart the changed process with a new worker id. |
+| `validation_failed` | any JSON route | A field is missing, malformed, too large, or outside allowed bounds. | Read `errors` or `validation_errors` and correct the payload. |
+
+## See Also
+
+- [Server API Reference](/docs/2.0/polyglot/server-api-reference)
+- [Worker Protocol](/docs/2.0/polyglot/worker-protocol)
+- [Task Queue Admission](/docs/2.0/polyglot/task-queue-admission)
+- [CLI Command Reference](/docs/2.0/polyglot/cli-reference)
diff --git a/docs/polyglot/server-api-reference.md b/docs/polyglot/server-api-reference.md
@@ -158,6 +158,10 @@ filesystem path. Object-storage policies such as `s3`, `gcs`, and `azure` use
 an explicitly configured filesystem disk and bucket/prefix settings on the
 server.
 
+For the full request-authority contract, including namespace resolution,
+role-scoped credentials, and worker registration fields, see
+[Namespace, Auth, And Worker Registration](/docs/2.0/polyglot/namespace-auth-workers).
+
 ## Bridge Adapters
 
 Bridge adapters are bounded ingress endpoints. They do not execute workflow
@@ -302,6 +306,7 @@ operation details into the nested `control_plane` object.
 ## See Also
 
 - [Server guide](/docs/2.0/polyglot/server)
+- [Namespace, Auth, And Worker Registration](/docs/2.0/polyglot/namespace-auth-workers)
 - [Worker Protocol](/docs/2.0/polyglot/worker-protocol)
 - [Task Queue Admission](/docs/2.0/polyglot/task-queue-admission)
 - [External Execution](/docs/2.0/polyglot/external-execution)
diff --git a/docs/polyglot/server.md b/docs/polyglot/server.md
@@ -315,6 +315,9 @@ Key field notes for client code:
 ## Connecting Workers
 
 Workers poll the server for tasks and execute workflow code or activities. See the [Worker Protocol](/docs/2.0/polyglot/worker-protocol) reference for the full API contract.
+For the route role matrix, namespace lookup rules, and exact worker
+registration payload, see
+[Namespace, Auth, And Worker Registration](/docs/2.0/polyglot/namespace-auth-workers).
 
 ### PHP Workers
 
diff --git a/docs/polyglot/worker-protocol.md b/docs/polyglot/worker-protocol.md
@@ -48,6 +48,11 @@ Read these fields before sending optional command fields:
 - `query_tasks`: server-routed workflow query tasks for external runtimes.
 - `non_retryable_failures`: workflow and activity failure metadata support.
 
+Before polling, each worker must register its namespace, task queue, runtime,
+supported type keys, and local capacity through `POST /api/worker/register`.
+The [Namespace, Auth, And Worker Registration](/docs/2.0/polyglot/namespace-auth-workers)
+reference freezes that registration payload and the role-scoped auth contract.
+
 ## Workflow Task Bridge
 
 The `WorkflowTaskBridge` contract defines how an external worker interacts with durable workflow tasks:
diff --git a/docs/search-and-navigation.md b/docs/search-and-navigation.md
@@ -33,6 +33,7 @@ common phrases to the smallest useful guide.
 | `CLI`, `dw command`, `json output` | [CLI](./polyglot/cli.mdx) | [CLI Command Reference](./polyglot/cli-reference.md) |
 | `Python`, `SDK`, `polyglot` | [Python SDK](./polyglot/python.md) | [CLI and Python Parity](./polyglot/cli-python-parity.md) |
 | `server mode`, `HTTP API`, `control plane` | [Server](./polyglot/server.md) | [Embedded to Server Migration](./polyglot/embedded-to-server.md) |
+| `namespace`, `auth`, `worker registration` | [Namespace, Auth, And Worker Registration](./polyglot/namespace-auth-workers.md) | [Server API Reference](./polyglot/server-api-reference.md), [Worker Protocol](./polyglot/worker-protocol.md) |
 | `worker protocol`, `external worker`, `heartbeats` | [Worker Protocol](./polyglot/worker-protocol.md) | [External Execution Surface](./polyglot/external-execution.md) |
 | `task queue`, `rate limit`, `admission` | [Task Queue Admission](./polyglot/task-queue-admission.md) | [Monitoring](./monitoring.md) |
 | `MCP`, `AI client`, `llms.txt` | [MCP Workflow Surface](./mcp-workflows.md) | [AI-Assisted Development](./ai-assisted-development.md), [Sample App](./sample-app.md) |
@@ -64,6 +65,9 @@ future edits cannot silently drop the route.
   external execution, reliability, and AI automation work.
 - [CLI Command Reference](./polyglot/cli-reference.md) is the command lookup
   page for scripts, CI, and agents.
+- [Namespace, Auth, And Worker Registration](./polyglot/namespace-auth-workers.md)
+  is the request-authority reference for server namespaces, role-scoped
+  credentials, and worker registration.
 - [AI-Assisted Development](./ai-assisted-development.md) lists the v2 LLM
   manifests, MCP tools, CLI contracts, Waterline facts, and SDK surfaces that
   automation should use instead of guessing from screenshots.
diff --git a/docs/topics.md b/docs/topics.md
@@ -40,6 +40,8 @@ the sample app. The links below group those surfaces by job.
 ## Control Plane And Polyglot
 
 - [Server](./polyglot/server.md) - use the standalone HTTP control plane.
+- [Server API Reference](./polyglot/server-api-reference.md) - call exact HTTP control-plane and worker-plane routes.
+- [Namespace, Auth, And Worker Registration](./polyglot/namespace-auth-workers.md) - align namespace headers, role-scoped credentials, and worker registration.
 - [Embedded to Server Migration](./polyglot/embedded-to-server.md) - move from Laravel-embedded execution to server mode.
 - [CLI](./polyglot/cli.mdx) - install and configure `dw`.
 - [CLI Command Reference](./polyglot/cli-reference.md) - script exact command shapes and output modes.
diff --git a/scripts/discoverability-contract.json b/scripts/discoverability-contract.json
@@ -25,6 +25,7 @@
       "title": "Control Plane And Polyglot",
       "links": [
         "polyglot/server.md",
+        "polyglot/namespace-auth-workers.md",
         "polyglot/embedded-to-server.md",
         "polyglot/cli.mdx",
         "polyglot/cli-reference.md",
@@ -104,7 +105,15 @@
       "source": "polyglot/worker-protocol.md",
       "links": [
         "polyglot/external-execution.md",
-        "polyglot/server.md"
+        "polyglot/server.md",
+        "polyglot/namespace-auth-workers.md"
+      ]
+    },
+    {
+      "source": "polyglot/server-api-reference.md",
+      "links": [
+        "polyglot/namespace-auth-workers.md",
+        "polyglot/worker-protocol.md"
       ]
     }
   ],
@@ -114,6 +123,7 @@
     "agent-tooling-contract.md",
     "polyglot/cli-reference.md",
     "polyglot/cli-python-parity.md",
+    "polyglot/namespace-auth-workers.md",
     "polyglot/external-execution.md",
     "agent-operating-loop.md",
     "sample-app.md"
@@ -157,13 +167,19 @@
     {
       "query": "server mode http api control plane",
       "target": "polyglot/server.md",
-      "related": ["polyglot/embedded-to-server.md"],
+      "related": ["polyglot/embedded-to-server.md", "polyglot/namespace-auth-workers.md"],
       "aliases": ["standalone server", "HTTP", "control-plane"]
     },
+    {
+      "query": "namespace auth worker registration",
+      "target": "polyglot/namespace-auth-workers.md",
+      "related": ["polyglot/server-api-reference.md", "polyglot/worker-protocol.md"],
+      "aliases": ["X-Namespace", "DW_WORKER_TOKEN", "worker_id", "task_queue"]
+    },
     {
       "query": "worker protocol external worker heartbeats",
       "target": "polyglot/worker-protocol.md",
-      "related": ["polyglot/external-execution.md"],
+      "related": ["polyglot/external-execution.md", "polyglot/namespace-auth-workers.md"],
       "aliases": ["polling", "leasing", "heartbeats"]
     },
     {
diff --git a/scripts/reference-docs-contract.json b/scripts/reference-docs-contract.json
@@ -93,6 +93,38 @@
         "/api/system/retention/pass"
       ]
     },
+    {
+      "path": "polyglot/namespace-auth-workers.md",
+      "title": "Namespace, Auth, And Worker Registration",
+      "minimumCodeFences": 6,
+      "requiredHeadings": [
+        "Request Authority",
+        "Auth Roles",
+        "Namespace Contract",
+        "Worker Registration Contract",
+        "Polling And Visibility",
+        "Error Surface"
+      ],
+      "requiredTerms": [
+        "DW_WORKER_TOKEN",
+        "DW_OPERATOR_TOKEN",
+        "DW_ADMIN_TOKEN",
+        "X-Namespace",
+        "X-Durable-Workflow-Control-Plane-Version: 2",
+        "X-Durable-Workflow-Protocol-Version: 1.0",
+        "reason: \"namespace_not_found\"",
+        "reason: \"workflow_definition_changed\"",
+        "reason: \"task_queue_mismatch\""
+      ],
+      "requiredEndpoints": [
+        "/api/cluster/info",
+        "/api/namespaces",
+        "/api/workflows",
+        "/api/worker/register",
+        "/api/worker/workflow-tasks/poll",
+        "/api/task-queues/orders"
+      ]
+    },
     {
       "path": "polyglot/cli-reference.md",
       "title": "CLI Command Reference",
diff --git a/sidebars.js b/sidebars.js
@@ -125,6 +125,7 @@ const sidebars = {
       items: [
         'polyglot/server',
         'polyglot/server-api-reference',
+        'polyglot/namespace-auth-workers',
         'polyglot/embedded-to-server',
         'polyglot/cli',
         'polyglot/cli-reference',
