The Weble Cloud API allows external applications and scripts to interact with Weble gateways remotely through the cloud platform. It uses a two-step authentication process: first authenticate with the cloud to get an access token, then authenticate with a specific gateway (host) to get a session token. Once authenticated, all gateway API endpoints are accessible through the cloud proxy.
This is useful for:
The authentication process has two steps:
POST /api/token with your cloud credentials → returns an access_tokenPOST /api/hosts/<hostId>/api/auth with the gateway credentials → returns a sessionIdOnce both tokens are obtained, all subsequent requests to the gateway are made through the cloud proxy using the session cookie.
Cloud credentials → /api/token → access_token
↓
Gateway credentials → /api/hosts/<id>/api/auth → sessionId
↓
API requests → /api/hosts/<id>/api/<endpoint> (with session cookie)
POST https://<cloud>/api/token
Content-Type: application/json
{
"username": "your_cloud_username",
"password": "your_cloud_password"
}
Response: an access token object. Include it as Authorization: Bearer <access_token> in subsequent requests.
POST https://<cloud>/api/hosts/<hostId>/api/auth
Authorization: Bearer <access_token>
Content-Type: application/json
{
"username": "gateway_username",
"password": "gateway_password"
}
Response: { "sessionId": "..." } — use this as a cookie (WBLSUPSID=<sessionId>) for gateway API requests.
Once authenticated, all gateway API endpoints are accessible through the cloud proxy:
GET https://<cloud>/api/hosts/<hostId>/api/<endpoint>
Cookie: WBLSUPSID=<sessionId>
For example, to get the list of gateways on a host:
GET https://<cloud>/api/hosts/<hostId>/api/supervision/gateways/getGateways
The following script demonstrates the full authentication flow and a gateway API request:
var cloud = 'wbc.weble.ch'
var proxyUsername = 'YOUR_CLOUD_USERNAME'
var proxyPassword = 'YOUR_CLOUD_PASSWORD'
var host = 'HOST_ID'
var username = 'HOST_USERNAME'
var password = 'HOST_PASSWORD'
var access_token;
var https = require('https')
// Generic HTTPS request helper
function request(options, callback) {
var body = options.data
var finish = false
delete options.data
if (!options.headers) options.headers = {}
if (typeof body == 'object') options.headers['Content-Type'] = 'application/json'
if (access_token) options.headers['Authorization'] = 'Bearer ' + access_token.access_token
function done() {
if (finish) return
finish = true
callback(...arguments)
}
var req = https.request(options, res => {
var chunks = [];
res.on('data', data => chunks.push(data))
res.on('end', () => {
let resBody = Buffer.concat(chunks) + ''
try { resBody = JSON.parse(resBody); } catch (e) {}
callback(res.statusCode == 200 ? null : res.statusCode, resBody)
})
})
req.on('error', done);
if (typeof body == 'object') req.write(JSON.stringify(body))
else if (body) req.write(body);
req.end();
}
// Step 1: Get cloud access token
function getToken(username, password, callback) {
request({
host: cloud,
path: '/api/token',
method: 'POST',
data: { username: username, password: password }
}, function(err, result) {
if (err) return callback(err)
access_token = result
callback(null, access_token)
})
}
// Step 2: Get gateway session token
function getGatewayToken(host, username, password, callback) {
request({
host: cloud,
path: '/api/hosts/' + host + '/api/auth',
method: 'POST',
data: { username: username, password: password }
}, function(err, result) {
if (err) return callback(err)
callback(null, result.sessionId)
})
}
// Step 3: Make gateway API requests
function gatewayRequest(host, token, options, callback) {
options.path = '/api/hosts/' + host + '/api' + options.path
request(Object.assign({
host: cloud,
headers: { 'Cookie': 'WBLSUPSID=' + token }
}, options || {}), callback)
}
// Run
getToken(proxyUsername, proxyPassword, function(err) {
if (err) throw 'Unable to get cloud token: ' + err
console.log('Cloud login successful')
getGatewayToken(host, username, password, function(err, token) {
if (err) throw 'Unable to get gateway token: ' + err
console.log('Gateway token received:', token)
// Example: get list of gateways
gatewayRequest(host, token, {
method: 'GET',
path: '/supervision/gateways/getGateways'
}, function(err, result) {
console.log('Gateways:', result)
})
})
})
| Parameter | Description |
|---|---|
cloud |
The Weble Cloud server hostname (e.g. wbc.weble.ch). |
proxyUsername / proxyPassword |
Your Weble Cloud account credentials. |
host |
The Host ID of the gateway you want to access. This can be found in the cloud dashboard. |
username / password |
The local credentials of the gateway (the same credentials used to log into the gateway's web interface directly). |
| Method | Endpoint | Description |
|---|---|---|
| GET | /supervision/gateways/getGateways |
List all gateways on the host. |
| GET | /supervision/gateways/getAddresses?gateway_id=<id> |
Get all addresses for a specific gateway. |
| POST | /supervision/gateways/writeValue |
Write a value to an address. Body: { "id": <addressId>, "value": <value> } |
| GET | /supervision/gateways/readValue?id=<addressId> |
Read the current value of an address. |
Note: The full gateway API documentation will be available in a dedicated page. The endpoints above are the most commonly used for scripting.