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.

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_...

Endpoint reference

Bridge and requester

Workers

Accounts and claimed tokens

Worker lifecycle

1. List the queue or poll for a pending task using a worker API key.
2. Store the returned leaseToken. The task changes from pending to leased.
3. Perform the real work.
4. Post to /response or /fail using the same worker API key and lease token.
5. 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. Send a stable, unique workerId with each poll so the account and administrator consoles can distinguish worker processes. Workers show as live for two minutes after their last poll.

Each token retains up to 20 pending or leased and 10 completed or failed requests, for at most seven days. Request bodies are limited to 512 KiB.

Connect a custom domain

1. Prepare the organization

Sign in at /account, enroll an authenticator, and choose the organization that owns the white-label hostname.

2. Register the hostname

curl -X POST "https://service.example.com/api/v2/domains" \
  -H "authorization: Bearer $SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d '{"organizationId":"$ORG_ID","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.

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