@mastra/core/dist/docs/references/docs-server-auth-workers.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Workers

When workers run in separate processes from the API, they communicate over HTTP. The orchestration worker calls the API's step execution endpoint to run workflow steps on the API server. Push-mode PubSub brokers (like Google Cloud Pub/Sub in push mode) can also deliver events directly to the API's event endpoint. This is a distinct integration path from pull-mode workers, which pull events from the broker themselves. Both HTTP endpoints require authentication when an auth provider is configured.

## How it works

Worker authentication uses the same auth pipeline as the rest of your Mastra server. The orchestration worker sends credentials with each HTTP request, and the server's configured `authenticateToken` provider validates them.

| Endpoint                                                    | Used by                                       | Purpose                            |
| ----------------------------------------------------------- | --------------------------------------------- | ---------------------------------- |
| `POST /api/workflows/:workflowId/runs/:runId/steps/execute` | Orchestration worker via `HttpRemoteStrategy` | Execute a workflow step on the API |
| `POST /api/workflows/events`                                | Push-mode brokers (GCP Pub/Sub, SNS)          | Deliver workflow events to the API |

Both routes have `requiresAuth: true`. When no auth provider is configured, they're publicly accessible.

> **Warning:** When deploying workers as separate processes, always configure an auth provider on the server. Without one, the step execution and event endpoints are open to any caller.

## Setting up worker auth

### Configure an auth provider on the server

Use any Mastra auth provider. `SimpleAuth` works well for worker tokens:

```typescript
import { Mastra } from '@mastra/core/mastra'
import { SimpleAuth } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({
      tokens: {
        [process.env.WORKER_TOKEN!]: {
          id: 'worker',
          name: 'Orchestration Worker',
          role: 'worker',
        },
      },
    }),
  },
  // ... storage, pubsub, etc.
})
```

### Set the worker token

On each worker container, set `MASTRA_WORKER_AUTH_TOKEN` to a token that the server's auth provider recognizes:

```yaml
services:
  api:
    environment:
      WORKER_TOKEN: ${WORKER_TOKEN}
      # ... other env vars

  orchestration-worker:
    environment:
      MASTRA_WORKER_AUTH_TOKEN: ${WORKER_TOKEN}
      MASTRA_STEP_EXECUTION_URL: http://api:4111/api # Use HTTPS in production
      # ... other env vars
```

```bash
WORKER_TOKEN=sk-worker-secret-token
```

These examples use `http://` for local development. In production, use HTTPS URLs and terminate TLS with a service mesh or ingress controller. See [Security recommendations](#security-recommendations).

The orchestration worker reads `MASTRA_WORKER_AUTH_TOKEN` and sends it as a `Bearer` token in the `Authorization` header on every step execution request.

## Auth credential types

The `HttpRemoteStrategy` supports three credential formats. The default (`bearer`) covers most setups.

### Bearer token

Set `MASTRA_WORKER_AUTH_TOKEN` and the strategy sends `Authorization: Bearer <token>`:

```bash
MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token
```

### API key header

Send the credential as `x-worker-api-key` instead of `Authorization`:

```typescript
import { HttpRemoteStrategy } from '@mastra/core/worker'

const strategy = new HttpRemoteStrategy({
  serverUrl: 'http://api:4111/api', // Use HTTPS in production
  auth: { type: 'api-key', key: process.env.WORKER_API_KEY! },
})
```

Your server's auth provider must read the `x-worker-api-key` header to validate this credential.

### Custom header

Use any header name and value:

```typescript
import { HttpRemoteStrategy } from '@mastra/core/worker'

const strategy = new HttpRemoteStrategy({
  serverUrl: 'http://api:4111/api', // Use HTTPS in production
  auth: {
    type: 'header',
    name: 'X-Internal-Service-Key',
    value: process.env.INTERNAL_KEY!,
  },
})
```

## Push-mode broker auth

When using a push-mode PubSub (like Google Cloud Pub/Sub), the broker POSTs events directly to the `/api/workflows/events` endpoint. The broker attaches its own credentials. For example, Google Cloud Pub/Sub sends a Google-signed OIDC token.

Your auth provider's `authenticateToken` callback must recognize whatever credential the broker sends. See your broker's documentation for the authentication scheme it uses.

## Security recommendations

- **Use different tokens for different worker types.** This lets you revoke access to one worker without affecting others.
- **Rotate tokens on a schedule.** Update the `WORKER_TOKEN` environment variable and restart the affected containers.
- **Use TLS in production.** Worker-to-API communication should go over HTTPS to protect tokens in transit. This applies to all environments, including Kubernetes clusters and Docker networks. Use a service mesh (e.g., Istio, Linkerd) or TLS-terminating ingress to encrypt internal traffic.
- **Restrict network access.** The step execution and event endpoints are internal. If possible, keep them off the public internet using network policies or firewall rules.

## Related

- [Auth overview](https://mastra.ai/docs/server/auth): Available auth providers and how they work
- [Token-based auth](https://mastra.ai/docs/server/auth/simple-auth): Token-to-user mapping authentication
- [Worker deployment](https://mastra.ai/guides/deployment/mastra-workers): Set up split worker processes
- [Workers reference](https://mastra.ai/reference/workers/overview): Configuration details for all worker types
- [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`