Service Bridge API

Turn an incoming HTTP request into a task, let an authenticated worker lease it, and return the worker response to the original requester through polling.

SendRequester calls an API path.

QueueService Bridge creates a pending task.

WorkA worker key leases and handles it.

ReturnRequester polls the task result.

Quick start

1. Generate a bridge token and worker key

curl -X POST https://service.example.com/new/token \
  -H "content-type: application/json" \
  -d '{"workerKeyCount":1,"workerKeyNames":["Primary worker"]}'

Keep both returned values. The bridge token identifies the queue. The raw workerApiKey is shown only once.

2. Send a request

curl -X POST "https://service.example.com/$TOKEN/orders/123" \
  -H "content-type: application/json" \
  -d '{"sku":"book","quantity":1}'

The response is 202 Accepted with a taskId and resultUrl.

3. Poll from a worker

curl -X POST "https://service.example.com/_bridge/$TOKEN/poll" \
  -H "authorization: Bearer $WORKER_KEY" \
  -H "content-type: application/json" \
  -d '{"workerId":"orders-worker","path":"/orders/123"}'

4. Complete the task

curl -X POST "https://service.example.com/_bridge/$TOKEN/tasks/$TASK_ID/response" \
  -H "authorization: Bearer $WORKER_KEY" \
  -H "content-type: application/json" \
  -d '{"leaseToken":"lease_...","statusCode":200,"body":{"ok":true}}'

The same worker key that leased the task must submit the response.

5. Fetch the result

curl "https://service.example.com/_bridge/$TOKEN/tasks/$TASK_ID"

Authentication

Requester result polling uses the bridge token in the URL. Worker operations require a worker API key in either header:

Authorization: Bearer sbw_...
X-Service-Bridge-Worker-Key: sbw_...

Account and organization endpoints use the session token returned by user registration or login:

Authorization: Bearer sb_session_...

Worker keys created before a token is claimed are unrestricted. Organization Admins can create claimed-token keys limited to exact paths, prefix paths such as /orders/*, and the poll, list, complete, or fail actions.

Endpoint reference

Bridge and requester

Method	Path	Purpose	Auth
POST	`/new/token`	Create a bridge token and initial worker keys.	None
ANY	`/:token/:path`	Convert an HTTP request into a pending task.	Bridge token in path
GET	`/_bridge/:token/tasks/:taskId`	Read pending, completed, or failed result state.	Bridge token in path

Workers

Method	Path	Purpose
POST	`/_bridge/:token/poll`	Lease the oldest pending task, optionally filtered by exact path or task id.
GET	`/_bridge/:token/tasks`	List visible tasks with optional path, status, and limit filters.
POST	`/_bridge/:token/tasks/:taskId/response`	Complete a leased task.
POST	`/_bridge/:token/tasks/:taskId/fail`	Fail a leased task.
GET / POST	`/_bridge/:token/worker-keys`	List or create unrestricted keys for an unclaimed token.
DELETE	`/_bridge/:token/worker-keys/:keyId`	Revoke an unclaimed-token worker key.

Accounts and claimed tokens

Method	Path	Purpose
POST	`/api/auth/register`	Create a user account and session.
POST	`/api/auth/login`	Create a user session.
GET	`/api/auth/me`	Read the current user.
POST	`/api/auth/logout`	End the current session.
GET / POST	`/api/v2/organizations`	List or create organizations.
POST	`/api/v2/organizations/:orgId/members`	Add or update an organization member.
POST	`/api/v2/tokens/:token/claim`	Attach a bridge token to an organization.
GET / POST	`/api/v2/tokens/:token/worker-keys`	List or create scoped worker keys.
DELETE	`/api/v2/tokens/:token/worker-keys/:keyId`	Revoke a scoped worker key.
PUT	`/api/v2/tokens/:token/security`	Configure IP allow, deny, and auto-ban controls.
POST	`/api/v2/tokens/:token/domains`	Map custom hostnames to a token.

Worker lifecycle

List the queue or poll for a pending task using a worker API key.
Store the returned leaseToken. The task changes from pending to leased.
Perform the real work.
Post to /response or /fail using the same worker API key and lease token.
The requester reads the final status and response from the result endpoint.

Revoking a worker key returns tasks currently leased by that key to the pending queue.

Connect a custom domain

1. Claim the bridge token

2. Register the hostname

curl -X POST "https://service.example.com/api/v2/tokens/$TOKEN/domains" \
  -H "authorization: Bearer $SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d '{"domains":["sb.example.com"]}'

3. Configure DNS and TLS

For a subdomain, create a CNAME to the configured service endpoint. For an apex domain, use an ALIAS, ANAME, flattened CNAME, or a CDN/reverse proxy.

Registered domains show as pending provisioning until Caddy's on-demand TLS flow obtains a certificate and the first HTTPS request reaches Service Bridge.

4. Preserve the original hostname

The proxy must forward either Host: sb.example.com or X-Forwarded-Host: sb.example.com. Forward X-Forwarded-For as well so token IP security rules see the real client.

5. Call the custom URL

curl -X POST "https://sb.example.com/$TOKEN/orders/123" \
  -H "content-type: application/json" \
  -d '{"sku":"book"}'

The custom hostname is a white-label entrypoint for the same portal and API surface. Keep the bridge token in the request path so Service Bridge knows which queue should receive the task.

Plans and limits

Token	Requests	Rolling tasks	Inactivity
Anonymous	60/min	60	24 hours
Claimed Free	100/min	100	30 days
Claimed Pro	600/min	600	No expiry