Authentication & OTP Flow

Clients authenticate using their registered mobile number. The system verifies identity via a WhatsApp/SMS One-Time Password (OTP) before granting access to device endpoints.

1. Requesting an OTP

Send a request with the mobile number in the URL path. This sends a 6-digit OTP code to the registered number on WhatsApp.

2. Verifying the OTP

Verify the code received. On success, the response returns a JWT bearer access token.

Controlling Smart Devices

Once authenticated, devices can be triggered directly in one of three ways by targeting a device's [DEVICE_ID] content_copy (find these under the Devices tab):

What is the cURL Button & Why is it there?

Under the Generated APIs tab, each device endpoint includes a cURL button.

• What it is: cURL is a command-line tool used to transfer data with URLs. It runs directly inside terminal shells (like Command Prompt, PowerShell, Linux Terminal, or macOS Terminal).
• Why it's there: It allows installers and developers to immediately copy a working request command, paste it in their command terminal, and verify if the backend gateway successfully connects to Home Assistant. It serves as a rapid testing and debugging tool without needing to write custom software.

1. The 3 Authentication Methods Explained

This gateway provides three security levels to invoke endpoints (/api/device/:id/:action). Pick the method that fits your client integration:

• Type A: JWT Bearer Token (Secure Sessions)
  Authenticates using a JSON Web Token (JWT) in headers (Authorization: Bearer [TOKEN]) or query parameters (?token=[TOKEN]). Ideal for authenticated sessions.
• Type B: Mobile & OTP Parameters (Stateless Simple)
  Directly passes cleartext mobile number and active otp query parameters. Easiest setup but requires active OTP sessions.
• Type C: Stateless HMAC Request Signatures (Best Security)
  Client-side signed commands using the JWT_SECRET as the key. Ideal for automated widgets, home assistant buttons, and server scripts because it prevents token exposure and replay attacks.

2. Terminal Integration (cURL Commands)

Use the following commands inside shell terminals (Command Prompt, PowerShell, Linux/Mac Terminals) to trigger actions. Replace dev-12345 with your device ID and toggle with the action name.

A. JWT Token Auth

curl -X POST "http://[GATEWAY_IP]:9875/api/device/dev-12345/toggle" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json"

B. Mobile & OTP Parameters

curl -X POST "http://[GATEWAY_IP]:9875/api/device/dev-12345/toggle?mobile=9876543210&otp=768777" \
  -H "Content-Type: application/json"

C. Stateless HMAC Signatures

curl -X POST "http://[GATEWAY_IP]:9875/api/device/dev-12345/toggle" \
  -H "Content-Type: application/json" \
  -H "x-signature: computed_hmac_hex" \
  -H "x-timestamp: unix_epoch_milliseconds"

3. Client Request Signing Code Templates

Constructing request signatures requires joining TIMESTAMP:METHOD:PATH:BODY, hashing it with HMAC-SHA256 using the JWT_SECRET, and adding it to headers.

const crypto = require('crypto');
const axios = require('axios');

const JWT_SECRET = 'your_jwt_secret';
const GATEWAY_URL = 'http://gateway-ip:9875';
const deviceId = 'dev-12345';
const action = 'toggle';
const body = {}; 

const timestamp = Date.now().toString();
const path = `/api/device/${deviceId}/${action}`;
const bodyStr = Object.keys(body).length ? JSON.stringify(body) : '';
const message = `${timestamp}:POST:${path}:${bodyStr}`;

const signature = crypto.createHmac('sha256', JWT_SECRET).update(message).digest('hex');

axios.post(`${GATEWAY_URL}${path}`, body, {
  headers: {
    'Content-Type': 'application/json',
    'x-signature': signature,
    'x-timestamp': timestamp
  }
});

import time, hmac, hashlib, json, requests

JWT_SECRET = 'your_jwt_secret'
GATEWAY_URL = 'http://gateway-ip:9875'
device_id = 'dev-12345'
action = 'toggle'
body = {}

timestamp = str(int(time.time() * 1000))
path = f'/api/device/{device_id}/{action}'
body_str = json.dumps(body) if body else ''
message = f'{timestamp}:POST:{path}:{body_str}'

signature = hmac.new(
    JWT_SECRET.encode('utf-8'),
    message.encode('utf-8'),
    hashlib.sha256
).hexdigest()

headers = {
    'Content-Type': 'application/json',
    'x-signature': signature,
    'x-timestamp': timestamp
}
requests.post(f'{GATEWAY_URL}{path}', json=body, headers=headers)