Roles & Groups Reference

Overview

Billerang uses Keycloak client roles on the billerang-backend client, organized by domain. Roles follow a consistent naming convention, are read-only (defined at bootstrap), and are assigned to users exclusively through groups.

---

Naming Convention

All roles follow the pattern {domain}.{resource}.{scope}:

catalog.offers.manage
│         │       │
domain    resource scope

Segment	Values	Notes
domain	api, accounts, catalog, ordering, billing, finance	Logical grouping of functionality
resource	users, offers, invoices, payments, etc.	The entity being acted upon
scope	view, manage, run	The level of access

Scope semantics:

Scope	Grants
view	Read-only access: list and get operations
manage	Full CRUD: create, update, delete in addition to view
run	Execute-only: trigger jobs, run scripts (no configuration changes)

---

Complete Role Catalog

api domain — Platform Administration (17 roles)

These roles control access to the connect portal's IAM and administrative features. They use the api.* prefix because they live on the billerang-backend Keycloak client.

Role	Description
api.users.view	List and view user accounts
api.users.manage	Create, invite, update, and delete users
api.roles.view	View the role catalog
api.roles.manage	Reserved for future role management features
api.groups.view	List and view groups and their members
api.groups.manage	Create, update, delete groups; manage membership
api.security.view	View password policy, SSO config, and 2FA status
api.security.manage	Update password policy, configure SSO, enforce 2FA
api.settings.view	View platform settings
api.settings.manage	Update platform settings
api.jobs.view	View job definitions and execution history
api.jobs.run	Trigger job execution
api.jobs.manage	Create, update, and delete job definitions
api.scripts.view	View script definitions
api.scripts.run	Execute scripts
api.scripts.manage	Create, update, and delete scripts
api.audit.view	View audit logs and activity history

---

accounts domain — Customer Hierarchy (10 roles)

Role	Description
accounts.customers.view	View customer accounts (CRM)
accounts.customers.manage	Create and update customers
accounts.customerAccounts.view	View customer accounts (payment-level)
accounts.customerAccounts.manage	Manage customer accounts
accounts.billingAccounts.view	View billing accounts
accounts.billingAccounts.manage	Manage billing accounts
accounts.userAccounts.view	View user accounts
accounts.userAccounts.manage	Manage user accounts
accounts.subscriptions.view	View subscriptions
accounts.subscriptions.manage	Manage subscriptions

---

catalog domain — Product & Pricing (12 roles)

Role	Description
catalog.offers.view	View offer templates
catalog.offers.manage	Create and update offer templates
catalog.products.view	View product templates
catalog.products.manage	Manage product templates
catalog.services.view	View service templates
catalog.services.manage	Manage service templates
catalog.charges.view	View charge templates
catalog.charges.manage	Manage charge templates
catalog.pricePlans.view	View price plan matrices
catalog.pricePlans.manage	Create and update price plan matrices
catalog.discounts.view	View discount plans
catalog.discounts.manage	Manage discount plans

---

ordering domain — Quoting & Orders (8 roles)

Role	Description
ordering.quotes.view	View quotes
ordering.quotes.manage	Create and update quotes
ordering.orders.view	View commercial orders
ordering.orders.manage	Create and manage orders
ordering.cpq.view	View CPQ (Configure-Price-Quote) definitions
ordering.cpq.manage	Manage CPQ configurations
ordering.contracts.view	View contracts
ordering.contracts.manage	Manage contracts

---

billing domain — Invoicing & Billing Runs (12 roles)

Role	Description
billing.invoices.view	View invoices
billing.invoices.manage	Generate, validate, and manage invoices
billing.billingRuns.view	View billing run history
billing.billingRuns.manage	Create and execute billing runs
billing.creditNotes.view	View credit notes
billing.creditNotes.manage	Issue and manage credit notes
billing.wallets.view	View prepaid wallet balances
billing.wallets.manage	Top up and manage wallets
billing.rating.view	View rated events and EDRs
billing.rating.manage	Reprocess and manage rating
billing.mediation.view	View CDR mediation records
billing.mediation.manage	Manage mediation processing

---

finance domain — Payments & Receivables (14 roles)

Role	Description
finance.payments.view	View payment records
finance.payments.manage	Process and manage payments
finance.refunds.view	View refunds
finance.refunds.manage	Issue and manage refunds
finance.dunning.view	View dunning campaigns and levels
finance.dunning.manage	Configure and manage dunning
finance.accountReceivables.view	View AR aging and receivables
finance.accountReceivables.manage	Manage account receivables
finance.paymentMethods.view	View customer payment methods
finance.paymentMethods.manage	Manage payment methods and mandates
finance.accounting.view	View accounting codes and entries
finance.accounting.manage	Manage accounting configuration
finance.reporting.view	View financial reports
finance.reporting.manage	Generate and export reports

---

Default Groups

Six groups are created during tenant bootstrap. They cannot be deleted. Their descriptions can be updated; role assignments reflect the platform's intended access patterns.

Platform Admin

Purpose: Full platform access for administrators and IT operations.

All domains: All 73 roles.

Typical members: Platform owner, IT administrator, lead developer.

---

Account Manager

Purpose: Customer-facing operations — manage accounts, view billing, and handle orders.

Domain	Access
api	All api.*.view roles
accounts	All accounts.* roles (view + manage)
catalog	All catalog.*.view roles
ordering	All ordering.* roles (view + manage)
billing	billing.invoices.view, billing.billingRuns.view
finance	finance.payments.view

Typical members: Sales, customer success, account operations.

---

Billing Manager

Purpose: Billing and invoicing operations.

Domain	Access
api	All api.*.view roles
accounts	All accounts.*.view roles, accounts.billingAccounts.manage
billing	All billing.* roles (view + manage)
finance	finance.payments.view, finance.accountReceivables.view

Typical members: Billing operations, invoice administrators.

---

Catalog Manager

Purpose: Product and pricing management.

Domain	Access
api	All api.*.view roles
catalog	All catalog.* roles (view + manage)
ordering	All ordering.*.view roles

Typical members: Product managers, pricing analysts.

---

Finance Manager

Purpose: Payments, collections, and financial reporting.

Domain	Access
api	All api.*.view roles
accounts	accounts.billingAccounts.view, accounts.customerAccounts.view
billing	billing.invoices.view
finance	All finance.* roles (view + manage)

Typical members: CFO, AR team, collections, treasury.

---

Viewer

Purpose: Read-only access across all domains. Useful for executives, auditors, and third-party reviewers.

All domains: All *.view roles (73 view roles, no manage roles).

---

Creating Custom Groups

When the built-in groups do not match your team's needs, create a custom group:

curl -X POST "https://connect.billerang.com/api/portal/groups" \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Team",
    "description": "Customer support — view accounts and invoices only",
    "roles": [
      "accounts.customers.view",
      "accounts.billingAccounts.view",
      "billing.invoices.view",
      "finance.payments.view"
    ]
  }'

Custom groups behave identically to built-in groups — you can add and remove members, update their role sets, and delete them when no longer needed.

---

Role Inheritance Model

Billerang does not use role hierarchies. There is no concept of "manage inherits view." Each role is independently assigned.

However, the built-in groups are designed so that manage-level users always also have view-level roles. When creating custom groups, follow the same pattern: if you add billing.invoices.manage, also add billing.invoices.view.

# Correct — user can see and manage invoices
"roles": ["billing.invoices.view", "billing.invoices.manage"]

# Missing view — user may encounter UI issues (manage without list/read)
"roles": ["billing.invoices.manage"]

---

Client Credentials Flow — Service Accounts

Service accounts (integrations, ETL pipelines, external systems) authenticate using OAuth 2.0 Client Credentials. They receive a bearer token with roles derived from their Keycloak group memberships, exactly like human users.

Best practice: create a dedicated service account per integration

Integration: ERP export job
  → Keycloak client: erp-export-client
  → Service account user: service-account-erp-export-client
  → Group membership: "Finance Viewer" (custom group with only finance.*.view roles)

This gives the ERP export job read-only access to financial data and nothing else. If the client secret is compromised, the blast radius is limited to that group's roles.

What roles does my service account have?

# Get a token
TOKEN=$(curl -s -X POST "https://auth.billerang.com/realms/billerang/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=erp-export-client" \
  -d "client_secret=$CLIENT_SECRET" | jq -r '.access_token')

# Inspect the session — roles are in the response
curl -X GET "https://api.billerang.com/api/v1/auth/session" \
  -H "Authorization: Bearer $TOKEN"

---

Connect Portal Roles

In addition to the billerang-backend client roles above, the connect component itself uses a separate set of roles on the billerang-connect Keycloak client. These control access to the connect API:

Role	Description
connect:org-admin	Full organization management in connect
connect:user-manager	User invitation and removal
connect:viewer	Read-only portal access

These roles are not visible in the billing portal's role catalog. They are managed internally by the connect bootstrap process.