403 Forbidden on Device Telemetry API endpoints: SKU-gated feature requires account-level permission grant

Android

If you're receiving a 403 Forbidden error when calling Device Telemetry API endpoints, your account may not have the Device Telemetry feature enabled. This article explains why this happens and how to resolve it.

Understand the issue

Device Telemetry API access is a feature that must be enabled at the account level. Even if you have enterprise admin roles and valid API keys, you'll receive a 403 Forbidden error with the message {"message":"Forbidden: You don't have permission to access this resource"} if your account hasn't been provisioned with this feature.

This error affects all telemetry endpoints:

• GET /v2/devices/{device_id}/telemetry/
• GET /v2/devices/{device_id}/events/
• GET /v2/devices/{device_id}/heartbeat/
• GET /v2/devices/{device_id}/metrics/
• GET /v2/devices/{device_id}/status/

Verify your endpoint syntax

Before requesting the entitlement, confirm you're calling the correct endpoints. Check the OpenAPI documentation for Device Telemetry to ensure your endpoint paths are accurate.

Note: Common path mistakes like /api/v2/devices/{device_id}/apps/ are invalid. The correct path for device apps is GET /v2/devices/{deviceId}/device-apps/.

Request the Device Telemetry feature

Device Telemetry API access must be enabled by Esper Support at your account level. Contact Esper Support with the following information:

• Your enterprise UUID
• Your enterprise short code
• Your host URL (for example: xtjny-api.esper.cloud)
• A copy of your API request that returns 403

The Support team will enable the Device Telemetry feature on your account and confirm when it's active.

Test access after the feature is enabled

Once Esper Support confirms the telemetry feature is enabled, test access with this command:

curl -i -H "Authorization: Bearer ${ESPER_API_KEY}" \
 "https://{short_code}-api.esper.cloud/v2/devices/{device_id}/telemetry/"

You should receive a 200 OK response with telemetry data. If you still receive a 403, contact Esper Support again—the change may not have propagated yet.

Temporary workaround (v0 endpoints)

While waiting for the Device Telemetry feature to be enabled, you can access limited device information using these alternative endpoints:

• Device state: GET /device/v0/devices/{id}/devicestate
• Events (latest only, Android only): GET /device/{device_id}/status/?latest_event=0
• Heartbeat: GET /device/v0/heartbeat/{id}/

Note: These v0 endpoints return limited data. They do not include telemetry fields like battery_current, battery_temperature, signal strength history, or charging state history. Use them as a temporary solution only.

Still need help?

If you continue to receive 403 errors after the Device Telemetry feature has been enabled, or if you have questions about your account tier and available features, submit a support ticket.