Core Concepts

Roled is built around a small set of core concepts. Understanding how these concepts relate to each other will help you design your applications more effectively and make the most of Roled’s authentication and authorization features.

How Everything Fits Together

A project is the security boundary in Roled. Every user, role, resource, permission, and client belongs to exactly one project. Here is the high-level structure:

    graph TD
    A[Project] --> B[Users]
    A --> C[Roles]
    A --> D[Resources]
    D --> E[Permissions]
    A --> F[Clients]
    C --> E
    F --> E
    B --> C
    style B fill:#fff5ad,stroke:#aaaa33
    style F fill:#fff5ad,stroke:#aaaa33
  

There are two types of identities in Roled:

• Users represent human identities — they authenticate through OAuth 2.0 Authorization Code Flow.
• Clients represent machine identities — they authenticate through OAuth 2.0 Client Credentials Flow.

Both types of identities receive a JWT access token after authenticating. Roled then uses that token to resolve their permissions on every API request.

The Authorization Flow

Every incoming request follows the same process, regardless of whether it comes from a user or a machine:

    sequenceDiagram
    autonumber
    participant C as User or Client
    participant R as Roled API
    participant D as Database

    C->>R: Request with Bearer JWT
    R->>R: Validate JWT signature & expiry
    R->>D: Look up access token record
    D-->>R: Token status & identity
    R->>D: Resolve permissions for identity
    D-->>R: Permission list
    R->>R: Check required permission
    R-->>C: 200 OK or 403 Forbidden
  

Explore Core Concepts

Take a look at the following pages for the detailed information about each concept. You can start from Projects as it is the root of all other concepts, or just jump straight into the concept that interests you most: