Role Configuration

Roles are defined in your project's omnibase/permissions/roles.config.json file and synced to OmniBase using the CLI. These serve as templates that are copied to each tenant when created.

UI Components

OmniBase provides pre-built shadcn components for role management in @omnibase/shadcn:

How Role Templates Work

The roles.config.json file defines role templates. When a tenant is created, OmniBase copies the current state of these templates to create isolated roles for that specific tenant.

roles.config.json (Templates)
        │
        ▼ (copied on tenant creation)
┌───────────────────────────────────────┐
│  Tenant: Acme Corp                    │
│  ├── owner (copied from template)     │
│  ├── admin (copied from template)     │
│  └── member (copied from template)    │
└───────────────────────────────────────┘
┌───────────────────────────────────────┐
│  Tenant: Beta Inc                     │
│  ├── owner (copied from template)     │
│  ├── admin (copied from template)     │
│  └── member (copied from template)    │
└───────────────────────────────────────┘

Key Behaviors

Action	Effect
Update `roles.config.json`	Only affects newly created tenants
`tenantsApi.updateRole()`	Only affects that specific tenant's role
Add permission to template	Existing tenants do not automatically get it

If you add a new permission to a role template (e.g., tenant#some_new_permission to owner), existing tenants will not automatically receive it. However, tenant admins can manually add the permission to their tenant's role via the API or UI.

The Owner Role (Required)

The owner role must be created in your project. When a user creates a tenant, they are automatically assigned the owner role. If this role doesn't exist, tenant creation will fail.

The owner role is the only required role. Add it to your roles configuration:

omnibase/permissions/roles.config.json

{
  "roles": [
    {
      "id": "owner",
      "name": "Owner",
      "permissions": [
        "tenant#delete_tenant",
        "tenant#invite_user",
        "tenant#remove_user",
        "tenant#update_user_role"
      ]
    }
  ]
}

Owner Role Behavior

Auto-assigned: When a user creates a tenant, they automatically receive the owner role
Required: Tenant creation fails if the owner role doesn't exist
Full control: Owners typically have all tenant management permissions

Example Roles

The admin and member roles below are examples to help you understand the pattern. You can customize these or create entirely different roles based on your application's needs.

Full Control — Auto-assigned to tenant creator

Suggested permissions:

tenant#delete_tenant — Delete the organization
tenant#invite_user — Invite new members
tenant#remove_user — Remove members
tenant#update_user_role — Change member roles

{
  "id": "owner",
  "name": "Owner",
  "permissions": [
    "tenant#delete_tenant",
    "tenant#invite_user",
    "tenant#remove_user",
    "tenant#update_user_role"
  ]
}

Team Management — For team managers

Suggested permissions:

tenant#invite_user — Invite new members
tenant#remove_user — Remove members
tenant#update_user_role — Change member roles

{
  "id": "admin",
  "name": "Administrator",
  "permissions": [
    "tenant#invite_user",
    "tenant#remove_user",
    "tenant#update_user_role"
  ]
}

Standard Access — For regular team members

Suggested permissions:

tenant#view_users — View tenant members

{
  "id": "member",
  "name": "Member",
  "permissions": [
    "tenant#view_users"
  ]
}

Read-Only Access — For external collaborators

Suggested permissions:

tenant#view_users — View tenant members (optional)

{
  "id": "viewer",
  "name": "Viewer",
  "permissions": []
}

Complete Configuration Example

Here's a full roles.config.json with multiple roles:

omnibase/permissions/roles.config.json

{
  "roles": [
    {
      "id": "owner",
      "name": "Owner",
      "permissions": [
        "tenant#delete_tenant",
        "tenant#invite_user",
        "tenant#remove_user",
        "tenant#update_user_role",
        "tenant#view_users",
        "tenant#manage_billing"
      ]
    },
    {
      "id": "admin",
      "name": "Administrator",
      "permissions": [
        "tenant#invite_user",
        "tenant#remove_user",
        "tenant#update_user_role",
        "tenant#view_users"
      ]
    },
    {
      "id": "member",
      "name": "Member",
      "permissions": [
        "tenant#view_users"
      ]
    },
    {
      "id": "viewer",
      "name": "Viewer",
      "permissions": []
    }
  ]
}

Syncing Role Templates

After updating your roles configuration, sync it to OmniBase:

omnibase sync permissions

This command:

Reads your omnibase/permissions/roles.config.json
Validates the role definitions
Updates the role templates in OmniBase
Reports any errors or conflicts

Remember: Syncing only updates the templates. Existing tenants keep their current role configurations.

Managing Tenant Roles via API

The API methods below manage roles for a specific tenant, not the global templates.

Creating Roles for a Tenant

Create a new role within the current tenant:

import { V1TenantsApi } from '@omnibase/core-js';

const tenantsApi = new V1TenantsApi(config);

// Creates a role ONLY for the current tenant
const { data } = await tenantsApi.createRole({
  createRoleRequest: {
    roleName: 'developer',
    permissions: [
      'tenant#view_users',
    ],
  },
});

console.log('Created role:', data.data.role.id);

Listing Tenant Roles

// Lists roles for the current tenant only
const { data } = await tenantsApi.listRoles();

for (const role of data.data.roles) {
  console.log(`${role.role_name} (${role.id})`);
  console.log(`  Permissions: ${role.permissions.join(', ')}`);
  console.log(`  Users: ${role.user_ids.length}`);
}

Updating Tenant Role Permissions

This only updates the role for this specific tenant. Other tenants are not affected, and the global role templates remain unchanged.

// Updates the role ONLY for the current tenant
await tenantsApi.updateRole({
  roleId: roleId,
  updateRoleRequest: {
    permissions: [
      'tenant#view_users',
      'tenant#invite_user',  // Added permission
    ],
  },
});

Permission changes propagate immediately. All users with this role in this tenant will have updated permissions on their next request.

Deleting Tenant Roles

await tenantsApi.deleteRole({
  roleId: roleId,
});

Before deleting a role, all users must be reassigned to a different role. The owner role cannot be deleted.

Propagating Template Changes to Existing Tenants

If you update roles.config.json and want existing tenants to receive the new permissions, you have two options:

Option 1: Manual Update via API

Tenant owners/admins can add the new permission themselves:

// Tenant admin adds the new permission to their tenant's role
await tenantsApi.updateRole({
  roleId: 'owner',
  updateRoleRequest: {
    permissions: [
      // ... existing permissions
      'tenant#some_new_permission',  // New permission
    ],
  },
});

Option 2: Migration Script

For application-wide updates, create a migration script:

// Admin script to update all tenants
const tenants = await getAllTenants();  // Your admin API

for (const tenant of tenants) {
  const tenantsApi = new V1TenantsApi(configForTenant(tenant.id));

  const { data: roles } = await tenantsApi.listRoles();
  const ownerRole = roles.data.roles.find(r => r.role_name === 'owner');

  if (ownerRole && !ownerRole.permissions.includes('tenant#some_new_permission')) {
    await tenantsApi.updateRole({
      roleId: ownerRole.id,
      updateRoleRequest: {
        permissions: [
          ...ownerRole.permissions,
          'tenant#some_new_permission',
        ],
      },
    });
  }
}

Assigning Users to Roles

Via Invitation

When inviting users, specify their role:

await tenantsApi.createInvite({
  createTenantUserInviteRequest: {
    email: 'teammate@example.com',
    role: 'member',  // Role ID
    inviteUrl: 'https://app.example.com/auth/onboarding',
  },
});

See Team Invitations for the UserInvite component.

Updating Existing User's Role

await tenantsApi.updateTenantUserRole({
  updateTenantUserRoleRequest: {
    userId: targetUserId,
    role: 'admin',  // New role ID
  },
});

Use the UserViewer component to provide a UI for role management. See UserViewer Component.

Common Role Patterns

Next Steps

Custom Permissions — Define your own permission namespaces
Team Invitations — Invite users with specific roles
Permissions Concept — Deep dive into ReBAC internals

Role Configuration

RoleCreator Component

UserViewer Component

PermissionsSelector Component

Read-Only Viewer

Billing Manager

Project Lead

Contractor (Limited Project Access)

On this page