Roles & Permissions

Access in AndroidNexus is decided in two layers: the organization role you assign to a person, and the permissions the platform resolves for whoever is calling. This page explains both, and how they combine.

Overview

Two things decide whether a call succeeds:

1. Organization role: Owner, Admin or Member, assigned when you invite someone. Each endpoint admits a set of roles.
2. Permissions: named capabilities (androidnexus.<resource>:<verb>) resolved per organization for the person calling. For an API key, they are resolved for the person who created the key.

An endpoint may check either or both. Failing the role check returns 403 with PERMISSION_DENIED; failing the permission check returns 403 with missing_permission.

The authoritative answer is GET /auth/me

Rather than inferring what a credential can do from its role name, read authority.permissions from GET /auth/me. That array is the effective set the endpoints will honour.

Organization Roles

Owner

Complete control of the organization.

• Full access to all features and settings
• Can manage billing and subscription
• Can invite and remove any team member
• Only an owner may grant or revoke Owner
• An organization's last owner cannot be demoted or removed

Admin

Full operational access, without ownership.

• Full access to all features and settings
• Can author and deploy policies
• Can manage team members and API keys
• Can configure integrations
• Cannot grant or revoke ownership

Member

Day-to-day device work, without tenant administration.

• Can view and manage devices, and run device quick actions
• Can manage enrollment tokens
• Cannot view or edit policies or private apps
• Cannot view organization settings or audit logs
• Cannot manage team members or API keys

Permission Matrix

Owners and Admins can call every endpoint in the API reference. This table shows what a Member can call.

Endpoint	Permission key	Member
Devices
GET /devices, GET /devices/{id}	none	Yes
GET /devices/{id}/applications, GET /devices/{id}/events	none	Yes
GET /devices/{id}/telemetry/latest, /telemetry/history	telemetry:read	Yes
PATCH /devices/{id}/friendly-name, PATCH /devices/{id}/tags	none	Yes
POST /devices/bulk/add-tags, /bulk/remove-tags	none	Yes
Device commands
POST /devices/{deviceId}/commands	none	Yes
GET /commands, GET /devices/{deviceId}/commands/{commandId}	none	Yes
DELETE /devices/{deviceId}/commands/{commandId}	none	Yes
Enrollment
GET /enrollment_tokens, GET /enrollment_tokens/{token_id}, GET .../qr_data	none	Yes
POST /enrollment_tokens, PUT and DELETE /enrollment_tokens/{token_id}	none	Yes
Policies
Every /policies endpoint	policies:read / :write	No
Private apps
/content and /uploads	content:read / :write	No
Audit
GET /audit-logs	audit:read	No

"none" means the endpoint checks the role only.

An API key passes every role check and every permission check. Nothing in the table above bounds it. See API Keys.

Permissions

Above the role check, a guarded endpoint names a permission from the platform catalog. Permissions are spelled androidnexus.<resource>:<verb>:

Key	Covers
telemetry:read	Device telemetry reads
content:read / :write	Private apps; uploading and updating them
policies:read / :write	Policies, members, history; authoring and deploying
audit:read	The audit log

A caller lacking the key an endpoint names receives 403 with the code missing_permission. That is a grant problem rather than a credential problem: retrying with the same credential keeps failing until an owner or admin widens what it holds.

API Keys

An API key authenticates as a machine, and two things about it commonly surprise people.

Every key holds full access

A key is not a scoped credential

Every API key carries full administrator authority over your enterprise, whoever created it and whatever that person can do. A key can read and change every device, policy and private app, start remote control, and factory reset hardware.

A key is authenticated as an administrator and resolved against the entire permission catalog. Who created it makes no difference: creating a key under a restricted account does not produce a restricted key, and the scopes shown when a key is created do not narrow what it can reach.

There is no way to issue a key with a smaller permission set today. Scoping keys individually is planned, and this page will say so when it ships.

Until then, treat a key the way you would treat a root password:

• Keep it on a server you control. Never ship it to a browser, a mobile app or anything else a customer can read. Put a small backend in front of it and have your frontend call that, so the browser only ever receives short-lived, single-purpose tokens. Build Your Own Frontend walks through the pattern.
• Give each integration its own key, so you can revoke one without breaking the others. This limits blast radius, not authority.
• Rotate keys on a schedule, and revoke any key whose owner leaves.

GET /auth/me reports the authority of whatever credential you send, which is a quick way to see this for yourself.

Keys cannot manage access

API keys, users and team members are managed by a signed-in person in the console. Those endpoints admit a person and nothing else, so they refuse an API key with 403 and the code unauthorized_principal_kind. This is the one real limit on a key, and it holds even though the key is otherwise an administrator: a leaked key cannot create a replacement for itself, revoke other keys, or add users.

Owners and admins create and revoke keys under Settings → API Keys.

Changing Roles

Owners and Admins change team member roles from Settings > Team Members.

Role change effects

• Upgrading to Admin: the user immediately gains policy, settings and integration access.
• Downgrading to Member: the user loses policy and settings access on their next request.
• You cannot change your own role.
• The last owner cannot be demoted. Transfer ownership first by promoting another member to Owner.

Inviting Team Members

1. Go to Settings > Team Members
2. Click the Invite Member button
3. Enter their email address
4. Select their role (Owner, Admin, or Member)
5. Click Send Invitation

Only an existing Owner may invite someone directly as Owner. The invited user receives an email with instructions to join your organization, and the pending invitation can be re-sent or cancelled from the same page.

Best Practices

Principle of Least Privilege

Assign the minimum role needed for each person's job:

• IT Help Desk Staff: Member. Resolving tickets means running device quick actions and managing enrollment. They will not see policies.
• MDM Administrators: Admin. Policy authoring and settings both require it.

Treat API Keys as Full-Access Credentials

Least privilege does not reach API keys today: every key holds full administrator authority regardless of who created it, so creating one under a restricted account buys you nothing. See API Keys.

What does help is limiting exposure. Hold the key server-side, give each integration its own so one can be revoked alone, and rotate on a schedule.

Regular Access Reviews

• Remove members who no longer need access
• Downgrade roles where elevated access is no longer required
• Review outstanding API keys and revoke unused ones
• Keep at least two Owners, so the last-owner protection never strands you

Troubleshooting

403 with code missing_permission

The credential is valid, but it does not hold the permission the endpoint requires. The message names the missing key. Ask an Owner or Admin to grant it; retrying will not help.

403 with code unauthorized_principal_kind

An API key was used on an endpoint that manages access (API keys, users or team members). Make that change in the console as a signed-in person.

402 with code SUBSCRIPTION_REQUIRED

The organization has no active subscription. Nearly every endpoint returns this until billing is resolved; the response carries a redirect_url to the billing page. Retrying will not help.

403 with code PERMISSION_DENIED

The caller's role does not admit the operation. Most often this is a Member calling a policy, private app or audit log endpoint.

503 with code tenant_not_carried

Your organization is not yet provisioned on the platform identity service, so no permissions can be resolved for it. Do not retry; a backoff loop cannot clear this. Contact support.

"Access Restricted" on the Settings page

Your account has the Member role, which does not include settings access. Ask an Owner or Admin to upgrade you to Admin, or to make the change for you.

Can't invite team members

Only Admin and Owner can invite. Ask an existing Admin or the Owner.

Can't see audit logs

The audit log requires Admin or Owner.

Related Topics

• Settings Overview - General settings configuration
• Quick Start Guide - Getting started with AndroidNexus
• Best Practices - Security and operational guidelines