Docs
[IAM]

Permissions

Permissions represent the most granular level of access control within IAM. They define exactly what an identity is allowed to do within the PLTFRMS ecosystem.

Permissions are also commonly referred to as scopes in OAuth2 contexts.

What is a permission?

A permission is a single, atomic action or capability, such as:

  • users.read
  • users.write
  • invoices.create
  • payments.refund

Permissions are not assigned directly to users in most cases. Instead, they are used as building blocks within roles.

Permissions in the IAM model

Permissions sit at the lowest level of the IAM structure:

User → Group → Role → Permission

This ensures that access is always:

  • Structured (via roles and groups)
  • Consistent across the platform
  • Easy to manage at scale

Permissions and roles

Roles are composed of permissions.

This means:

  • A role defines a set of allowed actions
  • Permissions define the actual operations that can be executed
  • A user inherits permissions through their assigned roles

For example:

  • Role: Admin
    • users.read
    • users.write
    • organisations.manage

Permissions and OAuth2 scopes

In PLTFRMS, permissions are tightly integrated with OAuth2.

This means:

  • Permissions are mapped to OAuth2 scopes
  • Access tokens contain granted scopes
  • APIs validate permissions based on token scopes

This ensures that authorization works consistently across both internal and external integrations.

Realm and organisation context

Permissions are always evaluated within:

  • A Realm (isolation boundary)
  • An Organisation (business context)

This ensures that:

  • The same permission can behave differently per organisation
  • Access is always scoped to the correct tenant context
  • No permission exists outside its defined realm

Permission granularity

Permissions are designed to be:

  • Atomic — representing a single action
  • Composable — combined into roles
  • Reusable — shared across roles and clients
  • Context-aware — evaluated per realm and organisation

This allows IAM to remain both flexible and strict at the same time.

Types of permissions

IAM supports different categories of permissions:

  • Resource permissions — access to entities (users, invoices, etc.)
  • Action permissions — create, read, update, delete operations
  • System permissions — platform-level or administrative capabilities
  • Scoped API permissions — OAuth2-based API access scopes

Permission evaluation

When a request is made, IAM evaluates permissions by:

  1. Validating identity (user or client)
  2. Resolving roles via groups and assignments
  3. Aggregating all permissions from roles
  4. Checking required permission against granted set
  5. Enforcing realm and organisation context

Access is only granted if all conditions are satisfied.

Why permissions matter

Permissions are the foundation of all access control in IAM because they:

  • Define the exact actions allowed in the system
  • Enable fine-grained security control
  • Power OAuth2 scope-based authorization
  • Allow roles and groups to scale access management

Without permissions, IAM would not be able to enforce secure or granular access decisions.