> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.orbitdev.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Role-Based Access Control: app_role and Platform Permissions

> How Orbit enforces roles with app_role and platform permissions, protects the admin role, and prevents self-demotion through admin_change_user_role.

Orbit uses the existing `app_role` and platform-permission systems for authorization. These systems remain authoritative across the product and the Control Center. This page explains the role model, the protected admin role, and the safeguards around role mutation.

## Role systems

The platform has two complementary layers:

1. `app_role` — the primary role assigned to a user, such as `user`, `advertiser`, or `admin`.
2. Platform permissions — fine-grained capabilities that can be checked independently of the primary role.

Admin console access requires the protected `admin` role. Permission checks query `user_roles` server-side and never trust user-editable JWT metadata.

## Token mutations

Token mutations require both the `admin` role and the `tokens.adjust` permission. This means an administrator without the token permission cannot modify token balances or grants, even if they have broad access to other admin functions.

## Role mutation safeguard

Role mutations run only through `admin_change_user_role`. This function prevents an administrator from removing their own admin access. The check runs server-side and cannot be bypassed by client-side manipulation.

<Warning>
  Never allow direct updates to `user_roles` from client contexts. Always route role changes through `admin_change_user_role` so the self-demotion guard and audit trail remain intact.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.