Roles

BunBase includes a simple string-based role system. Roles are stored on each user record and included in every access token (JWT). They are evaluated server-side on every protected request.

How Roles Work

Roles are an array of strings on the user record:

{
  "id": "01JKW...",
  "email": "alice@example.com",
  "roles": ["admin", "editor"],
  "metadata": { "plan": "pro" }
}

The JWT roles claim mirrors this array:

{
  "sub": "01JKW...",
  "email": "alice@example.com",
  "roles": ["admin", "editor"],
  "iat": 1709900000,
  "exp": 1709900900
}

No roles are built-in or given special meaning by BunBase. You define all role names your app uses.

Assigning Roles

Via Admin API — set full roles array

PATCH /api/v1/admin/users/:id/roles
Authorization: Bearer <admin-secret>
Content-Type: application/json

{ "roles": ["admin", "editor"] }

Via Admin API — update user (also sets email, metadata, is_verified)

PATCH /api/v1/admin/users/:id
Authorization: Bearer <admin-secret>
Content-Type: application/json

{
  "roles": ["editor"],
  "is_verified": true,
  "metadata": { "plan": "pro", "display_name": "Alice" }
}

Response: the updated user object.

Via Studio

Open Auth → Users, click Edit on any user. The edit panel shows:

• Email field
• Email verified toggle
• Roles tag editor — type a role name and press Enter or click Add, click × to remove
• Metadata JSON editor — freeform JSON object

Using Roles in Collection Rules

Set a collection access rule to { "role": "name" } to restrict an operation to users with that role:

POST /api/v1/admin/collections
Authorization: Bearer <admin-secret>
Content-Type: application/json

{
  "name": "articles",
  "rules": {
    "read": "public",
    "create": { "role": "editor" },
    "update": { "role": "editor" },
    "delete": { "role": "admin" }
  }
}

Any user without the required role receives 403 Forbidden.

Role checks also apply to realtime subscriptions — a subscription to a role-restricted collection is denied at connect time with an error message.

User Metadata

metadata is a freeform JSON object stored alongside the user. It is not included in the JWT — fetch it by calling the user endpoint or via the Admin API. Use it for:

• Display name, avatar URL
• Plan tier or feature flags
• App-specific profile data

GET /api/v1/admin/users/:id
Authorization: Bearer <admin-secret>

The metadata is read-only for end users. Only admins can set or update it.

Security Notes

• Roles are embedded in the JWT at login time. If you change a user’s roles, the change takes effect on the next token refresh (up to 15 minutes delay on the access token).
• To force immediate effect, revoke the user’s active sessions via the Admin API or Studio.
• Role strings are case-sensitive. "Admin" and "admin" are different roles.