Skip to main content

Authentication

The Heirs E-Invoicing Middleware uses two 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"
  }'

Which to use?​

ActionAuth required
Submit invoices from ERPx-api-key
View business settingsx-api-key or Bearer JWT
Manage team membersx-api-key or Bearer JWT
Upload FIRS credentialsx-api-key or Bearer JWT
FIRS OAuth integrationPOST /v1/auth/oauth/firs

Password Management​

EndpointPurpose
POST /v1/auth/forgot-passwordRequest a password reset email
GET /v1/auth/validate-reset-token/{token}Check a reset token is valid
POST /v1/auth/reset-passwordSet a new password using the token
POST /v1/auth/set-passwordSet a temporary password (first login)

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