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.
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_...
/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. Optional ?wait=15. | Bridge token in path |
Workers
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /_bridge/:token/poll | Lease the oldest pending task, optionally filtered by exact path or task id; optional ?wait=15. |
| 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/totp/setup | Create an authenticator enrollment QR and manual key. |
| POST | /api/auth/totp/enroll | Verify and save a user authenticator. |
| POST | /api/auth/password | Reset the signed-in user password with an authenticator code. |
| POST | /api/auth/password/reset | Reset a user password by email with an authenticator code. |
| POST | /api/auth/logout | End the current session. |
| GET / POST | /api/v2/organizations | List or create organizations. |
| PUT / DELETE | /api/v2/organizations/:orgId | Rename or delete an organization and its dependent data (Admin). |
| POST | /api/v2/organizations/:orgId/members | Add 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/claim | Attach a bridge token to an organization. |
| DELETE | /api/v2/tokens/:token | Delete a claimed token and its request and worker data (Admin). |
| GET / POST | /api/v2/domains | List or register organization-owned custom hostnames. |
| GET | /api/v2/requests?view=activity | Show the latest 20 active and 10 completed requests across account tokens. |
| GET | /api/v2/workers | Show workers polling tokens in the account's organizations. |
| GET / POST | /api/v2/tokens/:token/worker-keys | List or create scoped worker keys. |
| GET | /api/v2/worker-keys | List existing worker keys across the account's tokens. |
| 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. |
Worker lifecycle
- List the queue or poll for a pending task using a worker API key.
- Store the returned
leaseToken. The task changes frompendingtoleased. - Perform the real work.
- Post to
/responseor/failusing 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. 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
| 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 |