Scoped API keys via RBAC: workaround for read-only permissions

Android

When your integration needs read-only or limited access to Esper APIs, all API keys grant full read-write permissions to your enterprise by default. Using Esper's role-based access control (RBAC), you can create a dedicated service account with restricted permissions and generate an API key that inherits only those permissions.

Why this happens

Esper API keys inherit the permissions of the user account that generates them. Because there is no native per-key permission scoping, the only way to restrict what an API key can do is to restrict the user account it belongs to.

Before you begin

RBAC is available on Plus and Ultimate plans. To confirm your plan includes it, go to Settings → Subscription in the Esper Console and verify your tier. If role management options are not visible under Settings → Roles & Permissions, your plan does not include RBAC.

Steps

1. Create a custom role with only the permissions your integration needs.
   Go to Settings → Roles & Permissions and select Create Role. Enable only the specific permissions required — for example, View Devices and View Groups — and disable all write and command permissions. Save the role with a name that reflects its scope, such as read-only-integration. Naming the role clearly prevents it from being mistakenly edited or reused for broader access later.
2. Create a dedicated service account user and assign the new role.
   Go to Settings → Users and select Invite User. Enter a real, receivable email address for the service account — for example, api-readonly@yourcompany.com — and assign the role you created in step 1. The invitation link is sent to that address, so a generic alias or forwarding address that cannot receive external email will prevent setup.
3. Accept the invitation and set a password for the service account.
   Open the invitation email sent to the service account address and follow the link to the Esper Console. Set a password and complete sign-in. The service account must complete this step before an API key can be generated; an unaccepted invitation cannot produce a key.
4. Sign out of your admin account and sign in as the service account.
   Select your account menu in the Esper Console and choose Sign Out. Sign in using the service account credentials. Generating the key while signed in as your admin account will produce a key with admin-level permissions, defeating the purpose of this setup.
5. Generate the API key from within the service account session.
   Go to API Key Management and select Generate API Key. Copy the key immediately and store it in your secrets manager or credential vault — the full key is not shown again after you navigate away.
6. Sign back into your admin account.
   Sign out of the service account and sign back in with your admin credentials to return to normal console access.

Verify

Verify: Test the API key against two endpoints before deploying it to your integration:

• Call a write endpoint, such as POST /api/v0/enterprise/{id}/devices/{device_id}/reboot/. It should return HTTP 403 Forbidden.
• Call a read endpoint, such as GET /api/v0/enterprise/{id}/devices/. It should return HTTP 200 OK.

Both responses confirm the key is correctly scoped. If the write endpoint returns 200, the key was generated while signed in as the wrong user — repeat steps 4 and 5.

Important considerations

• Service account dependency: If the service account is deactivated or deleted, the API key stops working immediately. Document the account and mark it as a production dependency so it is not removed accidentally.
• Multiple permission profiles: If you need API keys with different permission sets — for example, one for device reads and one for group management — create a separate service account and RBAC role for each profile.
• Credential rotation: API keys do not expire automatically. Follow your organization's credential rotation practices and treat the service account password and API key as sensitive secrets.

If this doesn't resolve it

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

• You were signed in as the service account — not your admin account — when you generated the key.
• The service account has only the restricted role assigned, with no additional roles that include write permissions.
• You are testing with the key generated in the most recent session, not an older key generated previously.

If the issue persists, contact Esper Support and include the service account email address, the role name and its permission list, and the 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.