Authentication

The Heirs E-Invoicing Middleware uses three authentication mechanisms depending on who is making the request and what they are doing.

---

1. Tenant API Key (x-api-key)

Used by tenant systems (your ERP, backend, or integration layer) to make API calls on behalf of a registered tenant.

Pass the key in the x-api-key request header:

curl https://e-invoicing-staging.vercel.app/v1/tenants/{tenantId}/settings/business \
  -H "x-api-key: YOUR_TENANT_API_KEY"

API keys are created by an admin via POST /v1/tenants/{tenantId}/api-keys and scoped to specific permissions. They expire after a configurable number of days (1–3,650).

:::caution Never expose your API key Do not include it in client-side code, browser requests, or public repositories. Store it in environment variables only. :::

---

2. Bearer Token / JWT (Authorization: Bearer)

Used by team members (humans) who log in via email and password through the dashboard or direct API calls.

Login

curl -X POST https://e-invoicing-staging.vercel.app/v1/auth/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "yourpassword"
  }'

The response returns a JWT. Pass it as a Bearer token on subsequent requests:

curl https://e-invoicing-staging.vercel.app/v1/auth/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Token Refresh

curl -X POST https://e-invoicing-staging.vercel.app/v1/auth/refresh \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"

Team Member Login

curl -X POST https://e-invoicing-staging.vercel.app/v1/auth/team-member \
  -H "Content-Type: application/json" \
  -d '{
    "email": "member@company.com",
    "password": "memberpassword"
  }'

---

3. Admin Key (x-admin-key)

Used by platform administrators for cross-tenant management operations. This key has elevated privileges and should be kept strictly confidential.

curl https://e-invoicing-staging.vercel.app/v1/tenants/ \
  -H "x-admin-key: YOUR_ADMIN_KEY"

Admin key operations include: creating tenants, managing API keys, configuring event routing, accessing sandbox tools, and managing the FIRS dictionary.

---

Which to use?

Action	Auth required
Submit invoices from ERP	x-api-key
View business settings	x-api-key or Bearer JWT
Manage team members	x-api-key or Bearer JWT
Upload FIRS credentials	x-api-key or Bearer JWT
Create or revoke API keys	x-admin-key
Create or manage tenants	x-admin-key
Configure event routing	x-admin-key
Run sandbox tests	x-admin-key
FIRS OAuth integration	POST /v1/auth/oauth/firs

---

Password Management

Endpoint	Purpose
POST /v1/auth/forgot-password	Request a password reset email
GET /v1/auth/validate-reset-token/{token}	Check a reset token is valid
POST /v1/auth/reset-password	Set a new password using the token
POST /v1/auth/set-password	Set a temporary password (first login)

Password minimum length: 6 characters (login), 8 characters (reset).