Restricting Client Credentials to Workers

Use the Allowed Workers Policy when a client credential should only run selected SDK workers. This is useful for least-privilege worker deployments, environment-specific workers, tenant-specific workers, or separating teams and namespaces.

This guide applies to SDK worker clients that register workers, poll for work, and submit worker results by using API client credentials.

Client credentials authenticate as an underlying API client user identity. Because the SDK worker client acts as that user, worker execution restrictions are configured on the API client user record.

The API client user can be authorized in two broad ways:

• Roles grant broad worker execution.
• A worker execution policy grants narrow worker execution for specific worker queues.

Worker SDK clients use the client lifecycle APIs for register, poll, and submit. These operations are treated as one logical permission: Execute. A worker execution policy grants Execute access to specific worker queues.

Role-bearing users with worker execution roles can run all workers. Currently, Org Admin, Integration, and Developer roles can execute workers, so the Allowed Workers Policy is ignored for those users. For worker-only API clients, roles are not required. Remove roles from the API client user if you want the Allowed Workers Policy to be the enforcement mechanism.

If a user has no worker execution role and no access policy, worker registration, polling, and submission are denied.

1. Go to Administration -> Users.
2. Locate the API client user associated with the client credential.
3. Remove broad roles if the client should be restricted by worker policy.
4. In Allowed Workers Policy, add the allowed namespace and worker entries.
5. To allow all workers in a namespace, choose the namespace and worker All (*).
6. Save changes.

The worker should refresh behavior after writer and engine connectivity cache notifications. If needed, restart the worker client or wait briefly for cache propagation.

The underlying User Access Policy uses this JSON shape:

version identifies the policy format. Use "v1".

allowedWorkerExecutions is the list of worker execution patterns the API client user can execute. Use namespace:workerName as the recommended format for exact worker access.

Supported patterns:

The policy applies to SDK worker execution:

• Worker registration
• Worker poll
• Worker submit

These are all covered by Execute. Do not configure or reason about separate Register, Poll, or Submit permissions.

A client needs access to all workers it registers, polls, or submits for. If one worker in a registration or poll request is not allowed, the request is denied.

For submit authorization, Unmeshed resolves the submitted stepId to the actual worker step definition and checks that worker's namespace and name against the policy.

If worker registration fails with 403 ER_102 Access Denied, the client user usually has no role and the policy is missing one or more workers being registered.

Check the worker client logs for the list of workers the SDK is registering. Ensure every namespace:name in the registration or poll set is allowed by the API client user's Allowed Workers Policy.

If a role is still assigned, the policy may appear to have no effect because roles allow all workers. Remove broad roles from worker-only API client users when the policy should enforce access.

For submit failures, verify the completed step's worker definition matches an allowed namespace:name entry.