API key permission errors for Blueprints, app details, and per-device managed configs — role and endpoint guide

Android

When making API calls to update Blueprints, read detailed application metadata, or push per-device managed configurations, requests return 403 Forbidden or changes do not appear on devices as expected.

Why this happens

Esper API keys inherit the permissions of the user account they are associated with — there is no per-key permission scope. If the associated user account does not hold the Enterprise Admin role, write operations such as blueprints:patch and managed config pushes are rejected by the API. Read-only roles like Developer or Viewer are silently permitted on GET endpoints but blocked on PATCH endpoints, which can make the root cause easy to miss.

Steps

1. Confirm your user account has the Enterprise Admin role. In the Esper Console, go to Account → Team. Locate your user in the list and verify the Role column shows Enterprise Admin. If it shows Developer, Viewer, or any other role, contact your tenant administrator to request the Enterprise Admin role — without it, all write endpoints described below will return 403 Forbidden.
2. Generate or retrieve the API key tied to your Enterprise Admin account. In the Esper Console, go to API Management. Either generate a new key or copy an existing key that belongs to the Enterprise Admin user confirmed in the previous step. Store the key securely and do not share it.
3. Identify the correct API endpoint for your use case. With an Enterprise Admin API key, the following endpoints are available:
   • Update a Blueprint: PATCH /enterprise/{enterprise_id}/blueprint/{blueprint_id}/
   • Read detailed application metadata: GET /enterprise/{enterprise_id}/application/{application_id}/
   • Push a per-device managed configuration: PATCH /enterprise/{enterprise_id}/device/{device_id}/ — include a managed_config payload in the request body
   For full payload schemas and required fields, refer to your tenant's OpenAPI specification at https://<your-tenant>.esper.io/openapi.
4. Test each endpoint against a non-production resource before deploying to production. Send a PATCH request to a test Blueprint or a non-critical device and confirm the response is 200 OK. Testing against a live production Blueprint first risks unintended configuration changes syncing to enrolled devices immediately.
5. Confirm per-device managed config changes have taken effect on the device. After a successful PATCH, call GET /enterprise/{enterprise_id}/device/{device_id}/ and inspect the managed_config values in the response. If the values appear correct in the API response but are not reflected on the device, check whether a Blueprint assigned to that device is overriding the per-device config — Blueprint-level managed configurations take precedence over per-device overrides and are reapplied on every sync cycle.
6. Confirm Blueprint updates are syncing to enrolled devices. After patching a Blueprint, verify in Devices & Groups → [Device Name] → Activity Feed that a sync event has been recorded. Devices must be online and the Blueprint must be assigned to the target device or group. If no sync event appears within 15 minutes, confirm the device has an active network connection and the Blueprint is assigned correctly under Devices & Groups → Groups → [Group Name] → Blueprint.

Verify: A successful setup produces a 200 OK response for each endpoint, the device's Activity Feed shows a Blueprint sync event within 15 minutes of a patch, and the managed configuration values returned by GET /enterprise/{enterprise_id}/device/{device_id}/ match the values you pushed.

If this doesn't resolve it

Before contacting support, collect the following:

• The full API request and response, including headers and HTTP status code
• The enterprise_id, blueprint_id, or device_id used in the call
• A screenshot of the Team page in the Esper Console confirming the user role
• The timestamp of the failed request (in UTC)

Submit these details to Esper Support so the team can trace the request in the API logs and identify whether the issue is role-related, tenant-configuration-related, or a platform defect.

Still need help?

If the steps above don't resolve the issue, submit a support ticket with your device model, Android version, Esper Agent version, and a description of what you've already tried — this helps the support team investigate without a follow-up.