Users

A user represents a human identity in Roled. Users belong to a specific project and can be assigned a role that controls what they are allowed to do.

What Is a User?

In Roled, a user is an end-user of your application — someone who logs in, performs actions, and is subject to your application’s access rules.

Users are scoped to a single project. This means that a user belongs to exactly one project at a time.

The same user credentials might be used across multiple projects, but they are treated as separate users, and each registration is independent. This is the expected design decision, as each application always has its own user base. For example, a user with email alice@example.com might exist in Project A and Project B, but they are considered two different users.

Two Ways to Register Users

Roled supports two modes for managing users. You can mix both approaches within the same project, but generally it follows one approach for all users based on your project needs.

Fully Managed Users

Roled stores and manages all user data, including email, password, and profile information. Users authenticate through the Roled Auth page using the OAuth 2.0 Authorization Code Flow.

Best for: New projects that want a complete authentication system without building one from scratch.

    sequenceDiagram
    autonumber
    participant U as User
    participant Y as Your App
    participant R as Roled

    U->>Y: Click "Login"
    Y->>R: Redirect to Roled Auth page
    U->>R: Enter email & password
    R-->>Y: Redirect with authorization code
    Y->>R: Exchange code for access token
    R-->>Y: JWT access token
    Y->>R: Get current token details
    R-->>Y: User details with role and permissions
    Y->>Y: Build UI & logic based on roles & permissions
    Y-->>U: Display application content

To create a fully managed user, provide an email and password to the request:

curl --request POST \
  --url https://auth.roled.id/api/v1/projects/2JUSLUee46xG6iEwG8JwPc/users \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "Alice Smith",
    "avatar_url": "https://example.com/profiles/alice-smith.jpg",
    "email": "alice.smith@example.com",
    "password": "SecurePassword123!",
    "role_id": "2JRtjyxfZudzaJkFczgoUY"
  }'

Decoupled Users (Bring Your Own Users)

Your application manages its own user database and authentication. You register users in Roled using their external user ID — your application’s own identifier for that user. Roled stores only the role assignment, not credentials.

Best for: Projects that already have their own user system and want Roled to manage only roles and permissions.

    sequenceDiagram
    autonumber
    participant U as User
    participant Y as Your Backend
    participant R as Roled

    U->>Y: Login (your own auth system)
    Y->>Y: Authenticate user internally
    rect rgb(255, 245, 173)
    opt when access token is expired or not exist
      Y->>R: Get access token with Client Credential Flow
      R-->>Y: JWT access token
    end
    end
    Y->>R: Get user details
    R-->>Y: User details with role and permissions
    Y->>Y: Build UI & logic based on roles & permissions
    Y-->>U: Display application content

To create a decoupled user, provide your app’s user ID as external_user_id:

curl --request POST \
  --url https://auth.roled.id/api/v1/projects/2JUSLUee46xG6iEwG8JwPc/users \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "Bob Johnson",
    "avatar_url": "https://example.com/profiles/bob-johnson.jpg",
    "external_user_id": "a1d6f9d3dda5",
    "role_id": "2JRYtvorEzhNgMLHeqZiNo"
  }'

No need to provide email or password as the user is already authenticated by your application.

Role Assignment

Each user can be assigned one role at a time. The role determines what the user is allowed to do inside the project.

    graph LR
    U["Alice Smith"] --> R["Role: Store Manager"]
    R --> P1["products:create"]
    R --> P2["products:update"]
    R --> P3["products:read"]
    R --> P4["products:delete"]
    R --> P5["orders:read"]
    R --> P6["orders:update"]
    R --> P7["users:read"]

To change a user’s role, update the user with the new role_id.

Response Example

{
  "success": true,
  "data": {
    "id": "2JRtk7i2aEFKpsKTNx6YWR",
    "created_at": "2026-07-16T14:30:00Z",
    "updated_at": "2026-07-29T08:30:00Z",
    "email": "alice.smith@example.com",
    "external_user_id": "921f28239dcd",
    "display_name": "Alice Smith",
    "avatar_url": "https://example.com/profiles/alice-smith.jpg",
    "is_active": true,
    "is_email_verified": true,
    "role_id": "2JRtjyxfZudzaJkFczgoUY",
    "role_name": "Store Manager"
  }
}

Key Points

Users are scoped to a single project — each registration is independent per project.
You can choose Fully Managed Users or Decoupled Users mode to manage users.
A user is assigned one role, which determines their permissions.
Permissions are not embedded in the JWT — they are resolved server-side on every request.

Projects Roles