Role-Based Access Control (RBAC)

Metalogue provides enterprise-grade access control with 4 built-in roles and 15 granular permissions.

Overview

graph TB
    T[Tenant] --> R1[Owner]
    T --> R2[Admin]
    T --> R3[Member]
    T --> R4[Viewer]
    
    R1 --> P1[All Permissions]
    R2 --> P2[Most Permissions]
    R3 --> P3[Core Permissions]
    R4 --> P4[Read-Only]

Built-In Roles

Role	Description	Use Case
Owner	Full access + tenant settings	Founders, CTO
Admin	All operations except SSO/billing	Engineering leads
Member	Query, capture, connectors	Team members
Viewer	Read-only access	Stakeholders, auditors

Permission Matrix

Permission	Viewer	Member	Admin	Owner
`query`	✓	✓	✓	✓
`federate`		✓	✓	✓
`capture`		✓	✓	✓
`connector:read`	✓	✓	✓	✓
`connector:write`			✓	✓
`forget:self`		✓	✓	✓
`forget:any`			✓	✓
`audit:read`			✓	✓
`audit:export`			✓	✓
`tenant:read`			✓	✓
`tenant:write`				✓
`user:read`			✓	✓
`user:write`			✓	✓
`sso:configure`				✓
`federation:bridge`				✓

Permissions Reference

Query & Retrieval

Permission	Description
`query`	Execute federated queries
`federate`	Cross-node (cross-embedding) queries

Capture & Ingestion

Permission	Description
`capture`	Ingest documents via API
`connector:read`	View connector configurations
`connector:write`	Create, update, delete connectors

Unlearning

Permission	Description
`forget:self`	Create tombstones for own content
`forget:any`	Create tombstones for any content

Audit

Permission	Description
`audit:read`	View audit logs
`audit:export`	Export SOC2 compliance reports

Administration

Permission	Description
`tenant:read`	View tenant settings
`tenant:write`	Modify tenant settings
`user:read`	View user list
`user:write`	Invite, update, remove users
`sso:configure`	Configure SAML/OIDC SSO
`federation:bridge`	Create M&A tenant bridges

API Endpoints

List Users

GET /v1/auth/users
Authorization: Bearer mlo_xxx

Response:

{
  "users": [
    {
      "user_id": "uuid",
      "email": "alice@company.com",
      "name": "Alice Smith",
      "role": "admin",
      "is_active": true,
      "last_login": "2026-01-20T01:00:00Z"
    }
  ]
}

Invite User

POST /v1/auth/users/invite
Content-Type: application/json

{
  "email": "bob@company.com",
  "role": "member",
  "name": "Bob Jones"
}

Update User Role

PATCH /v1/auth/users/{user_id}
Content-Type: application/json

{
  "role": "admin"
}

Remove User

DELETE /v1/auth/users/{user_id}

Get Current User

GET /v1/auth/me

SDK Usage

TypeScript

const client = new MetalogueClient({ apiKey: API_KEY });

// List users
const users = await client.listUsers();

// Invite user
await client.inviteUser('bob@company.com', 'member');

Python

client = MetalogueClient(api_key=API_KEY)

# List users
users = await client.list_users()

# Invite user
await client.invite_user("bob@company.com", role="member")

Custom Roles

For enterprise customers, custom roles enable fine-grained permission sets:

POST /v1/auth/roles
Content-Type: application/json

{
  "name": "Data Steward",
  "permissions": [
    "query",
    "audit:read",
    "forget:any"
  ],
  "description": "Manages data quality and compliance"
}

Multi-Tenancy

Each tenant is isolated with its own:

User pool
Role assignments
Permission boundaries
Audit logs

Cross-tenant access requires explicit M&A federation bridges.

Best Practices

Use least privilege - Assign minimum necessary permissions
Regular audits - Review user roles quarterly
SSO integration - Map IdP groups to Metalogue roles
Service accounts - Use dedicated accounts for automation
Monitor usage - Track permission usage in audit logs

RBAC