Skip to main content

Permission Checks

These endpoints answer RBAC-style questions: "does the authenticated user have permission X?". All variants take a permission slug (or a list) and an optional context object. The optional context lets the server bring ABAC policies into the decision — for example, checking document.edit with {document_owner_id: 123} in context can evaluate ownership conditions alongside the role check.

Single Permission Check​

POST /api/v1/authz/check

Return whether the authenticated user has a single permission.

Request Body​

FieldTypeRequiredDescription
permissionstringYesPermission slug (e.g., document.edit)
contextobjectNoContextual attributes for ABAC evaluation

Simple Check​

curl -X POST https://api.example.com/api/v1/authz/check \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "document.edit"
  }'
{
  "allowed": true,
  "permission": "document.edit",
  "user_id": 123
}

Check with Context (ABAC)​

Include attributes about the target resource, request, or environment so ABAC policies can evaluate dynamic conditions.

curl -X POST https://api.example.com/api/v1/authz/check \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "document.edit",
    "context": {
      "document_id": 456,
      "document_owner_id": 123,
      "department": "engineering"
    }
  }'
Context Use Cases

Context is how you pass per-request facts — resource IDs, ownership, IP, device type, timestamps — that policies can reference. Attributes stored on the user or resource are merged with context at evaluation time.

Bulk Permission Check​

POST /api/v1/authz/check-bulk

Check many permissions in one request. The response contains an individual result for each permission. This is the efficient way to populate a page that conditionally shows several actions.

Request Body​

FieldTypeRequiredDescription
permissionsarrayYesArray of permission slugs to check
contextobjectNoShared context for all checks

Example​

curl -X POST https://api.example.com/api/v1/authz/check-bulk \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["document.view", "document.edit", "document.delete", "document.share"],
    "context": {
      "document_id": 456
    }
  }'
{
  "results": {
    "document.view": true,
    "document.edit": true,
    "document.delete": false,
    "document.share": true
  },
  "user_id": 123,
  "context": {
    "document_id": 456
  }
}

Check Any (OR)​

POST /api/v1/authz/check-any

Return allowed: true if the user has at least one of the listed permissions. Useful when multiple permissions can unlock the same feature.

curl -X POST https://api.example.com/api/v1/authz/check-any \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["document.owner", "document.editor", "admin.all"]
  }'
{
  "allowed": true,
  "permissions": ["document.owner", "document.editor", "admin.all"],
  "user_id": 123
}

Check All (AND)​

POST /api/v1/authz/check-all

Return allowed: true only if the user has every listed permission. Use for actions that require compound authority.

curl -X POST https://api.example.com/api/v1/authz/check-all \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["document.edit", "document.publish"]
  }'
{
  "allowed": false,
  "permissions": ["document.edit", "document.publish"],
  "user_id": 123
}

Response Fields​

FieldTypeDescription
allowedbooleanWhether the permission check passed
permissionstringThe permission that was checked (single check)
permissionsarrayThe permissions that were checked (any/all)
resultsobjectMap of permission → result (bulk check)
user_idintegerID of the authenticated user
contextobjectThe context that was provided

Common Patterns​

UI Button Visibility​

// Fetch permissions when loading a document editor
async function loadDocumentPermissions(documentId) {
  const response = await fetch('/api/v1/authz/check-bulk', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      permissions: ['document.edit', 'document.delete', 'document.share'],
      context: { document_id: documentId }
    })
  });

  const { results } = await response.json();

  // Show/hide UI elements based on permissions
  document.getElementById('edit-btn').hidden = !results['document.edit'];
  document.getElementById('delete-btn').hidden = !results['document.delete'];
  document.getElementById('share-btn').hidden = !results['document.share'];
}

Server-Side Guard​

# Check permission before processing request
def require_permission(permission):
    def decorator(func):
        def wrapper(*args, **kwargs):
            response = requests.post(
                f'{LUMOAUTH_URL}/api/v1/authz/check',
                headers={'Authorization': f'Bearer {get_token()}'},
                json={'permission': permission}
            )

            if not response.json().get('allowed'):
                raise PermissionDenied(f'Missing permission: {permission}')

            return func(*args, **kwargs)
        return wrapper
    return decorator

@require_permission('document.delete')
def delete_document(document_id):
    # User has permission, proceed with deletion
    ...