Skip to main content
POST
/
devices
/
{id}
/
wifi-config
/
grant
curl -X POST https://api.bota.dev/v1/devices/dev_abc123/wifi-config/grant \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_seconds": 900
  }'

{
  "grant_blob": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2025-06-15T12:15:00Z"
}
Create a WiFi configuration grant for a device. The grant is a stateless JWT that authorizes the companion app to send encrypted WiFi credentials to the device over BLE. The device uses the grant to derive a session key (K_session) for decrypting the WiFi credentials. No WiFi passwords are stored on the backend — the grant is purely an authorization token.
Only devices with the WiFi Upload capability (0x02) support WiFi configuration. Attempting to create a grant for a non-WiFi device returns a 400 error.

​
Authentication

Requires an API key with devices:write scope. 
curl -X POST https://api.bota.dev/v1/devices/dev_abc123/wifi-config/grant \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_seconds": 900
  }'

​
Path Parameters

​
id
string
required
The device’s unique identifier (e.g., dev_abc123).

​
Request Body

​
expires_in_seconds
integer
default:900
How long the grant is valid, in seconds. Minimum 60 (1 minute), maximum 3600 (1 hour). Default is 900 (15 minutes).

​
Response

Returns the grant blob and its expiration timestamp. 
{
  "grant_blob": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2025-06-15T12:15:00Z"
}

​
Response Fields

FieldTypeDescription
grant_blobstringSigned grant token to pass to device via BLE
expires_atstringGrant expiration timestamp (ISO 8601)

​
Usage Flow

  1. App scans for WiFi networks — the SDK provides scanNetworks() (Android) and getCurrentSSID() (both platforms) so users can pick a network
  2. App requests grant from your backend (this endpoint)
  3. App writes grant_blob to the device’s BLE WiFi Grant characteristic
  4. App encrypts WiFi credentials using a session key derived from the grant
  5. App writes encrypted credentials to the device’s BLE WiFi Credential characteristic
  6. Device connects to WiFi and reports status via the BLE WiFi Status characteristic
The React Native SDK provides scanNetworks() for step 1 and handles steps 3-6 automatically via BotaClient.devices.configureWiFi().
The grant_blob is a single-use authorization token. Each WiFi configuration attempt requires a fresh grant. Grants cannot be reused after expiration or after a successful configuration.