curl -X POST https://api.bota.dev/v1/devices/dev_abc123/token/refresh \
-H "Authorization: Bearer dtok_old_token_here..."
#include <HTTPClient.h>
#include <ArduinoJson.h>
#include <Preferences.h>
Preferences prefs;
void refreshDeviceToken() {
HTTPClient http;
http.begin("https://api.bota.dev/v1/devices/dev_abc123/token/refresh");
// Use current token
String currentToken = prefs.getString("device_token", "");
http.addHeader("Authorization", "Bearer " + currentToken);
int httpCode = http.POST("");
if (httpCode == 200) {
String response = http.getString();
StaticJsonDocument<256> doc;
deserializeJson(doc, response);
// Store new token
String newToken = doc["device_token"].as<String>();
prefs.putString("device_token", newToken);
Serial.println("Token refreshed successfully");
}
http.end();
}
{
"device_token": "dtok_new_token_a1b2c3d4e5f6g7h8i9j0..."
}
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing device token"
}
}
{
"error": {
"code": "forbidden",
"message": "Device token does not match device ID"
}
}
{
"error": {
"code": "bad_request",
"message": "Device must be bound to refresh token"
}
}
Refresh Device Token
Refresh a device token before it expires (4G devices only)
POST
/
devices
/
{id}
/
token
/
refresh
curl -X POST https://api.bota.dev/v1/devices/dev_abc123/token/refresh \
-H "Authorization: Bearer dtok_old_token_here..."
#include <HTTPClient.h>
#include <ArduinoJson.h>
#include <Preferences.h>
Preferences prefs;
void refreshDeviceToken() {
HTTPClient http;
http.begin("https://api.bota.dev/v1/devices/dev_abc123/token/refresh");
// Use current token
String currentToken = prefs.getString("device_token", "");
http.addHeader("Authorization", "Bearer " + currentToken);
int httpCode = http.POST("");
if (httpCode == 200) {
String response = http.getString();
StaticJsonDocument<256> doc;
deserializeJson(doc, response);
// Store new token
String newToken = doc["device_token"].as<String>();
prefs.putString("device_token", newToken);
Serial.println("Token refreshed successfully");
}
http.end();
}
{
"device_token": "dtok_new_token_a1b2c3d4e5f6g7h8i9j0..."
}
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing device token"
}
}
{
"error": {
"code": "forbidden",
"message": "Device token does not match device ID"
}
}
{
"error": {
"code": "bad_request",
"message": "Device must be bound to refresh token"
}
}
Refresh a device’s authentication token. The old token is revoked and a new token is returned. This allows devices to rotate their credentials without requiring a rebind operation.
This endpoint requires a device token, not an API key. The device must use its current valid token to request a new one.
string
required
The device’s unique identifier (e.g.,
dev_abc123). Must match the device associated with the token.curl -X POST https://api.bota.dev/v1/devices/dev_abc123/token/refresh \
-H "Authorization: Bearer dtok_old_token_here..."
#include <HTTPClient.h>
#include <ArduinoJson.h>
#include <Preferences.h>
Preferences prefs;
void refreshDeviceToken() {
HTTPClient http;
http.begin("https://api.bota.dev/v1/devices/dev_abc123/token/refresh");
// Use current token
String currentToken = prefs.getString("device_token", "");
http.addHeader("Authorization", "Bearer " + currentToken);
int httpCode = http.POST("");
if (httpCode == 200) {
String response = http.getString();
StaticJsonDocument<256> doc;
deserializeJson(doc, response);
// Store new token
String newToken = doc["device_token"].as<String>();
prefs.putString("device_token", newToken);
Serial.println("Token refreshed successfully");
}
http.end();
}
{
"device_token": "dtok_new_token_a1b2c3d4e5f6g7h8i9j0..."
}
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing device token"
}
}
{
"error": {
"code": "forbidden",
"message": "Device token does not match device ID"
}
}
{
"error": {
"code": "bad_request",
"message": "Device must be bound to refresh token"
}
}
Token Lifecycle
┌─────────────────┐
│ Bind Device │ ──► Returns initial dtok_*
└────────┬────────┘
│
▼
┌─────────────────┐
│ Device Active │ ◄─────────────────┐
│ (use dtok_*) │ │
└────────┬────────┘ │
│ │
▼ │
┌─────────────────┐ ┌─────────────┴───────────┐
│ Refresh Token │ ──► │ Old token revoked │
│ │ │ New dtok_* returned │
└─────────────────┘ └─────────────────────────┘
│
▼
┌─────────────────┐
│ Unbind Device │ ──► Token revoked, device unbound
└─────────────────┘
When to Refresh
We recommend refreshing tokens proactively rather than waiting for expiration. Consider refreshing:
- Every 7-14 days during normal operation
- After a firmware update
- If you suspect the token may have been compromised
Security Notes
- Only one valid token exists per device at any time
- The old token is immediately invalidated when refreshed
- If a refresh fails, the old token remains valid
- Unbinding a device revokes the token permanently
The new device token is only shown once in the response. Store it securely on the device immediately. If lost, you must unbind and rebind the device to get a new token.
Was this page helpful?
⌘I