Platform Roles
The Heirs E-Invoicing Middleware operates with four distinct roles, each with different access levels and responsibilities.
Tenant
A tenant is a registered business entity on the platform — a company that has onboarded to use the middleware for FIRS e-invoicing compliance.
Each tenant has:
- A unique
tenantId - Their own API keys (
x-api-key) - Their own ERP sync configuration
- Their own FIRS credentials (certificate + public key)
- A team of members who can manage their account
Tenant statuses:
| Status | Meaning |
|---|---|
pending | Registration submitted, awaiting review |
in_progress | Onboarding under way |
testing | Connected to sandbox, running test invoices |
active | Live on production |
rejected | Onboarding rejected |
suspended | Account suspended by admin |
inactive | Deactivated |
Team Member
Team members are users who belong to a tenant's account. They authenticate with email/password (JWT) and perform actions on behalf of the tenant.
Roles:
| Role | Permissions |
|---|---|
admin | Full access — manage team, credentials, ERP config, invoices |
member | Operational access — submit invoices, view logs |
viewer | Read-only — view invoices and reports |
Team members can be invited via email. An invitation link is sent; on acceptance they set a password and gain access.
Platform Admin
Platform admins manage all tenants across the system. They authenticate using the x-admin-key header (not a tenant API key).
Admin capabilities:
- Create and manage tenants
- Configure supported ERP types
- Manage the FIRS data dictionary
- Configure event routing per tenant
- Sandbox testing and transform validation
- Suspend or deactivate tenant accounts
FIRS (Federal Inland Revenue Service)
FIRS is the Nigerian tax authority that receives transmitted invoices. The middleware handles all communication with FIRS on behalf of tenants — tenants do not interact with FIRS directly.
The middleware:
- Generates IRNs (Invoice Reference Numbers) per FIRS specification
- Signs invoices using tenant-provided PEM certificates
- Transmits invoices to FIRS in UBL 2.1 format
- Receives acknowledgements and routes them back to the tenant