Skip to main content

List Permissions

Return every permission granted to the authenticated user, together with where that permission comes from (role, group, or inherited). Useful when a client needs to render a UI conditional on many permissions, or when you are debugging why a user can or cannot perform an action.

GET /api/v1/authz/permissions

When to Use This​

  • Render UI elements conditionally on the full permission set.
  • Show the user what they can do on a profile or settings page.
  • Capture effective permissions for audit or compliance.
  • Diagnose authorization behavior — see the exact list the server sees.

Request​

Attach the access token; no request body is needed.

curl -X GET https://api.example.com/api/v1/authz/permissions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response​

{
  "user_id": 123,
  "permissions": [
    {
      "slug": "document.view",
      "description": "View documents",
      "source": "role:Viewer"
    },
    {
      "slug": "document.edit",
      "description": "Edit documents",
      "source": "role:Editor"
    },
    {
      "slug": "document.create",
      "description": "Create new documents",
      "source": "role:Editor"
    },
    {
      "slug": "user.view",
      "description": "View user profiles",
      "source": "role:Admin"
    },
    {
      "slug": "user.manage",
      "description": "Manage users",
      "source": "role:Admin"
    }
  ],
  "count": 5
}

Response Fields​

FieldTypeDescription
user_idintegerID of the authenticated user
permissionsarrayArray of permission objects
countintegerTotal number of permissions

Permission Object​

FieldTypeDescription
slugstringUnique permission identifier (e.g., document.edit)
descriptionstringHuman-readable description
sourcestringWhere this permission comes from (e.g., role:Admin)
Permission Sources

A permission can reach a user through a directly assigned role, through a role attached to a group the user belongs to, or through role inheritance. The endpoint returns the effective (deduplicated) set.

Examples​

Building a Navigation Menu​

async function buildNavigation() {
  const response = await fetch('/api/v1/authz/permissions', {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });

  const { permissions } = await response.json();
  const permSet = new Set(permissions.map(p => p.slug));

  const navItems = [];

  // Always show dashboard
  navItems.push({ label: 'Dashboard', href: '/dashboard' });

  // Conditionally show based on permissions
  if (permSet.has('document.view')) {
    navItems.push({ label: 'Documents', href: '/documents' });
  }

  if (permSet.has('user.view') || permSet.has('user.manage')) {
    navItems.push({ label: 'Users', href: '/users' });
  }

  if (permSet.has('settings.manage')) {
    navItems.push({ label: 'Settings', href: '/settings' });
  }

  return navItems;
}

Caching the Permission Set​

class PermissionCache:
    """Cache user permissions for efficient checking"""

    def __init__(self, access_token):
        self.token = access_token
        self._permissions = None

    def load(self):
        """Fetch and cache all permissions"""
        response = requests.get(
            f'{LUMOAUTH_URL}/api/v1/authz/permissions',
            headers={'Authorization': f'Bearer {self.token}'}
        )
        data = response.json()
        self._permissions = {p['slug'] for p in data['permissions']}
        return self._permissions

    def has(self, permission):
        """Check if user has a permission"""
        if self._permissions is None:
            self.load()
        return permission in self._permissions

    def has_any(self, permissions):
        """Check if user has any of the permissions"""
        if self._permissions is None:
            self.load()
        return bool(self._permissions & set(permissions))

# Usage
perms = PermissionCache(access_token)
if perms.has('document.delete'):
    delete_document(doc_id)
Batch Checks

When you only need a handful of specific permissions for a page, use /api/v1/authz/check-bulk instead of downloading the full list.