SBN Services API Usage

The SBN Services Dashboard exposes its actions as an HTTP API, so you can automate them from your own scripts and tools -- checking service state, starting and stopping services, reading and downloading logs, editing settings, creating instances, and more. You authenticate with an API token you create on the API Tokens tab, and each request is allowed only if the token holds the matching feature for the target service.

The API is served by the Dashboard itself, over HTTPS, on the Dashboard's own address and port (for example https://your-server:port). All paths below are relative to that address.

Authenticating with a token

Send your token as a Bearer token in the Authorization header on every request:

That is the only credential the API needs. Notes:

• Use HTTPS -- never send a token over plain HTTP.
• If the token is missing, malformed, expired, or disabled, the request is rejected. A bearer token is used exactly as presented; the API does not fall back to any other credential.
• If you restricted the token to specific source addresses, the request must come from one of them.
• A token can only reach the action API. It can never reach token management or the administrator-only Dashboard actions, whatever features it holds.

How access is checked

Every action maps to a feature (a capability) and, for per-service actions, a target service. A request succeeds only when the token holds that feature and the target service is included in the token's scope. If the feature or the service is out of scope, the request is refused. Requests that return a list of services return only the services the token is allowed to see.

The feature required for each action is listed in the reference below. Feature names and what they grant are described on the API Tokens page.

Endpoint reference

{id} in a path is a service identifier as returned by the catalog. Paths beginning /api/service/{id}/... act on one service; the token must include that service.

Catalog and status

Service control

Logs

Files

Settings

Display name

Examples

The examples use curl; any HTTP client works the same way. Replace the host, port, and token.

Read the state of every service

Response:

Start a service

Response:

The start is issued immediately; poll /api/status to confirm the service reaches Running. The token must include the service.start feature and the frontend-1 service must be in its scope.

Stream live logs

The response is a Server-Sent Events stream that stays open. The first event reports the stream state, then one log event arrives per log line:

levels accepts any combination of info, warn and err; without it every level is sent. Lines starting with a colon (: keepalive) are comments emitted while the stream is idle and can be ignored. The token must include the logs.read feature for every requested service.

Errors

The API uses standard HTTP status codes:

• 200 -- the request succeeded.
• 401 -- no valid token was supplied (missing, malformed, expired, or disabled).
• 403 -- the token is valid but does not hold the required feature for the target service, or the action is administrator-only and never available to a token.
• 404 -- the service or resource in the path does not exist.

A refused request returns a short JSON body describing the reason; surface that message rather than a generic failure.

Related help

• API Tokens -- creating tokens, choosing features and services, rotating and revoking.
• The SBN Services Dashboard -- the same actions in the browser console.