Getting Started

Invora is a multi-tenant e-invoicing and billing platform. The API lets you:

• Issue compliant documents — UBL 2.1 invoices, credit notes, and debit notes with multi-country regulation support (ZATCA, Peppol, and more)
• Automate billing — plans, subscriptions, usage metering, wallets, and automated invoicing
• Manage organizations — self-service registration, role-based access, and multi-tenant platforms

This page is the orientation hub: it owns the canonical base URLs, points you at the right protocol, and links out to the deep-dive guides. New here? Jump straight to the Quickstart to send your first invoice.

Environments

Environment	Base URL	Auth issuer	Dashboard	Project-audience id
Production	https://gateway.invora.app	https://auth.invora.app	https://dashboard.invora.app	372376660185448530
Staging	https://stg-gateway.invora.app	https://stg-auth.invora.app	https://stg-dashboard.invora.app	372376692817133647

Most examples in the docs use the Production host. The Quickstart runs against Staging — a safe sandbox for your first end-to-end run.

Switching environments changes three values

To move any example between environments you must swap all of:

1. the gateway host — gateway.invora.app ↔ stg-gateway.invora.app
2. the auth issuer — auth.invora.app ↔ stg-auth.invora.app
3. the project-audience id in your scope — 372376660185448530 ↔ 372376692817133647

The third one is easy to miss. The project-audience id identifies the Invora project on a specific issuer, so presenting one environment's id to another environment's token endpoint fails with invalid_client and no token is issued. Swapping the host alone is not sufficient.

gRPC uses the same gateway host on port 443 over TLS (HTTP/2). See gRPC & Transcoding.

REST or gRPC?

Every Invora API is available over both protocols — gRPC is the canonical wire format, with automatic HTTP/JSON transcoding.

• REST/JSON — standard HTTP requests with JSON bodies. This is what the guides use. JSON fields are camelCase (proto freeze_immediately → JSON freezeImmediately).
• gRPC — binary protocol for high-throughput, server-to-server integrations. Proto modules are published on the Buf Schema Registry.

Field-name mapping, date/time types, enum encoding, proto modules, and code generation are all covered in gRPC & Transcoding.

Your First Call

The path from zero to an authenticated request is four steps:

flowchart LR
  A[Register in dashboard] --> B[Get access token]
  B --> C[Complete business profile]
  C --> D[Authenticated API calls]

1. Get credentials

Register at dashboard.invora.app, then register an application to obtain your client_id, client_secret, allowed scopes, and tenant ID. Full details — including the supported OIDC flows — are in Authentication.

2. Get an access token

TOKEN=$(curl -s -X POST https://auth.invora.app/oauth/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET" \
  --data-urlencode "scope=openid urn:zitadel:iam:org:project:id:372376660185448530:aud urn:zitadel:iam:user:resourceowner" \
  | jq -r '.access_token')

Both reserved scopes are required — see Authentication for why: the project-audience scope is what makes the gateway accept the token at all, and resourceowner embeds your home organization so requests resolve to your own tenant.

The access_token is an opaque reference token, not a JWT — pass it through verbatim as a Bearer credential; do not attempt to decode it. Every subsequent request includes Authorization: Bearer $TOKEN. (If you need user claims, use the id_token, which is a JWT — see Authentication.)

3. Complete your business profile

First-time setup creates your organization and activates a free trial:

curl -X POST https://gateway.invora.app/api/identity/v2/registration/complete-profile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Acme Trading Co.",
    "country": "SA",
    "capabilities": ["BUSINESS_CAPABILITY_EINVOICING"]
  }'

Response

{
  "tenantId": "317842069254438913",
  "businessName": "Acme Trading Co."
}

tenantId is your new organization's ID. Capabilities are BUSINESS_CAPABILITY_EINVOICING, BUSINESS_CAPABILITY_BILLING, or both.

4. Make an authenticated call

List your invoices (empty until you create one):

curl -X POST https://gateway.invora.app/api/v1/simple/invoices/list \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pagination": {"limit": "10"}}'

Response

{
  "items": [],
  "totalCount": "0"
}

All list endpoints return an items array plus totalCount. Filtering, sorting, pagination, and field selection follow one shared shape — see List APIs.

Cross-tenant access

Standard tokens are automatically scoped to their own tenant — no extra header needed. Multi-org callers (platforms, resellers) target a specific tenant with the x-zitadel-orgid header, validated against the caller's grants. See Multi-Tenancy.

Errors

Invora APIs use standard gRPC status codes (mapped to HTTP) augmented with domain-specific error details in a google.rpc.Status body. Status code reference, domain error codes, retry strategy, and rate limiting are all in Error Handling.

Where to Go Next

Goal	Guide
Send your first invoice end to end	Quickstart
OIDC flows, tokens, introspection	Authentication
Protocol details, camelCase, code-gen	gRPC & Transcoding
Filtering, sorting, pagination, masks	List APIs
Status codes and domain errors	Error Handling
Invoices, credit notes, debit notes	Simple Invoicing
Plans, subscriptions, usage, wallets	Billing
Platforms and connected businesses	Multi-Tenancy

Related

• Quickstart
• Authentication
• gRPC & Transcoding
• List APIs
• Error Handling
• Simple Invoicing
• Billing
• Multi-Tenancy