Skip to main content
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..."

{
  "device_token": "dtok_new_token_a1b2c3d4e5f6g7h8i9j0..."
}
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.
​
id
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..."

{
  "device_token": "dtok_new_token_a1b2c3d4e5f6g7h8i9j0..."
}

​
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.