Service Bridge API

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.

The worker task includes the incoming request headers, including Authorization, Cookie, API keys, and custom authentication headers. Workers can use the task method, path, query, headers, and body when calling an upstream API. Header names and JSON bodies may be normalized, so the task is an API-style representation rather than a byte-for-byte copy. Let the worker's HTTP client rebuild transport headers such as Host and Content-Length.

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,"headers":{"content-type":"application/json","x-request-id":"upstream-123"},"body":{"ok":true}}'

The same worker key that leased the task must submit the response. Include the upstream response headers in the JSON headers object. /fail accepts the same field when reporting an upstream failure.

5. Fetch the result

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

The final JSON contains response.statusCode, response.headers, and response.body. Frontend clients read worker-provided headers from response.headers for both completed and failed tasks. The result endpoint keeps its ServiceBridge JSON HTTP headers and status (200 for completed, 502 for failed); it does not set the worker-provided headers as literal HTTP response headers. In particular, a browser will not apply Set-Cookie or follow Location from that JSON object.

Optional long polling

Add ?wait=15 to a worker poll or requester result URL to hold the request for up to 15 seconds. The server responds promptly when matching work arrives or a task finishes. If no work arrives, worker polling returns its usual 200 response with task: null; if a result is still pending or leased, requester polling returns its usual 202 response. A completed or failed result returns immediately.

POST /_bridge/:token/poll?wait=15
GET /_bridge/:token/poll?wait=15
GET /_bridge/:token/tasks/:taskId?wait=15

wait is a number of seconds, capped at 20; 15 seconds is recommended. An omitted wait or wait=0 keeps immediate polling for existing clients. Invalid values return 400 INVALID_WAIT. Start the next poll after the previous one finishes and set the HTTP client timeout longer than the wait. The hold time is separate from the 15-minute worker task lease.

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-ServiceBridge-Worker-Key: sbw_...

The worker key is separate from the original request's authorization headers. The requester result endpoint and worker task listings include the original request headers. Worker-submitted response headers also appear in the result JSON. Anyone with a valid result URL can read task details without a worker key, so treat bridge tokens, task IDs, result URLs, and task output as sensitive.

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

MethodPathPurposeAuth
POST/new/tokenCreate a bridge token and initial worker keys.None
ANY/:token/:pathConvert an HTTP request into a pending task.Bridge token in path
GET/_bridge/:token/tasks/:taskIdRead pending, completed, or failed result state. Optional ?wait=15.Bridge token in path

Workers

MethodPathPurpose
GET / POST/_bridge/:token/pollLease the oldest pending task, optionally filtered by exact path or task id; optional ?wait=15.
GET/_bridge/:token/tasksList visible tasks with optional path, status, and limit filters.
POST/_bridge/:token/tasks/:taskId/responseComplete a leased task.
POST/_bridge/:token/tasks/:taskId/failFail a leased task.
GET / POST/_bridge/:token/worker-keysList or create unrestricted keys for an unclaimed token.
DELETE/_bridge/:token/worker-keys/:keyIdRevoke an unclaimed-token worker key.

Accounts and claimed tokens

MethodPathPurpose
POST/api/auth/registerCreate a user account and session.
POST/api/auth/loginCreate a user session.
GET/api/auth/meRead the current user.
POST/api/auth/totp/setupCreate an authenticator enrollment QR and manual key.
POST/api/auth/totp/enrollVerify and save a user authenticator.
POST/api/auth/passwordReset the signed-in user password with an authenticator code.
POST/api/auth/password/resetReset a user password by email with an authenticator code.
POST/api/auth/logoutEnd the current session.
GET / POST/api/v2/organizationsList or create organizations.
PUT / DELETE/api/v2/organizations/:orgIdRename or delete an organization and its dependent data (Admin).
POST/api/v2/organizations/:orgId/membersAdd or update an organization member.
DELETE/api/v2/organizations/:orgId/members?email=...Remove a member while keeping at least one Admin.
POST/api/v2/tokens/:token/claimAttach a bridge token to an organization.
DELETE/api/v2/tokens/:tokenDelete a claimed token and its request and worker data (Admin).
GET / POST/api/v2/domainsList or register organization-owned custom hostnames.
GET/api/v2/requests?view=activityShow the latest 20 active and 10 completed requests across account tokens.
GET/api/v2/workersShow workers polling tokens in the account's organizations.
GET / POST/api/v2/tokens/:token/worker-keysList or create scoped worker keys.
GET/api/v2/worker-keysList existing worker keys across the account's tokens.
DELETE/api/v2/tokens/:token/worker-keys/:keyIdRevoke a scoped worker key.
PUT/api/v2/tokens/:token/securityConfigure IP allow, deny, and auto-ban controls.

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.

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

TokenRequestsRolling tasksInactivity
Anonymous60/min6024 hours
Claimed Free100/min10030 days
Claimed Pro600/min600No expiry