API key returns 403 or has excess permissions — scope it with RBAC

Android

When an integration or script uses an Esper API key with more permissions than intended, any request it makes can read or modify devices, groups, and configurations beyond what the integration should touch — creating a security risk or causing unintended changes.

Why this happens

Esper API keys are tied to the user account that generates them and inherit that account's full permissions. Because admin accounts have read-write access across the enterprise, any key they generate does too. To limit what an API key can do, the user account that creates it must itself be limited — which is done by assigning a restricted RBAC role to a dedicated service account.

Before you begin

RBAC is available on Plus and Ultimate plans. To confirm your plan includes it, go to Esper Console → Settings → Subscription and check your plan tier before proceeding.

Steps

Create a custom role with only the permissions the integration needs.
Go to Esper Console → Settings → Roles & Permissions and select Create Role. Enable only the specific permissions required — for example, View Devices and View Groups — and leave all write and command permissions disabled. Save the role with a name that reflects its scope, such as read-only-integration. Naming it clearly prevents another admin from accidentally broadening its permissions later.
Create a dedicated service account user for this integration.
Go to Esper Console → Settings → Users and select Invite User. Enter a real, receivable email address for the service account (for example, api-readonly@yourcompany.com) — the invitation link must be accepted from a live inbox. Assign the role you created in step 1, then send the invitation.
Accept the invitation and set a password for the service account.
Open the invitation email, follow the link, and set a password for the service account. The account must complete this step before it can generate an API key. Store these credentials in your team's secrets manager and mark the account as a production dependency so it is not deactivated accidentally.
Sign out of your admin account and sign in as the service account.
Keys inherit permissions from the account that generates them, so you must be signed in as the service account — not your admin account — at the time of key creation.
Generate the API key from the service account session.
Go to Esper Console → API Key Management and select Generate API Key. Copy the key immediately and store it securely — it will not be shown again.

Verify

Verify: Test the key against two endpoints immediately after generating it:

A write endpoint — for example, POST /api/v0/enterprise/{id}/devices/{device_id}/reboot/ — should return HTTP 403 Forbidden.
A read endpoint — for example, GET /api/v0/enterprise/{id}/devices/ — should return HTTP 200 OK.

If both responses match expectations, the key is correctly scoped.

Important considerations

Service account dependency: If the service account is deactivated or deleted, the API key stops working immediately. Document it as a production dependency in your team's runbook.
Multiple permission profiles: If different integrations need different permission sets, create a separate service account and RBAC role for each one.
Key rotation: API keys do not expire automatically. Follow your organisation's credential rotation policy and treat the service account password and API key as sensitive secrets.

If this doesn't resolve it

If the API key still returns unexpected permissions after following these steps, confirm the following before contacting support:

The key was generated while signed in as the service account, not the admin account.
The service account has only the restricted role assigned — go to Esper Console → Settings → Users, find the service account, and verify no additional roles are listed.
The role itself has no write permissions enabled — go to Esper Console → Settings → Roles & Permissions, open the role, and review each permission toggle.

If the issue persists, contact Esper Support with the service account username, the role name and its permission list, and the API endpoint and HTTP response you are seeing.

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.