Admin APIs¶

Admin APIs are restricted to Invora platform administrators. They manage tenants, billing organizations, regulation configurations, and cross-tenant invoice views.

All admin endpoints require Invora.Admin.* scopes, which are granted only to platform administrator roles.

Admin Services¶

Service	Base Path	Purpose
TenantAdminService	`/api/admin/identity/v2/tenants`	Tenant lifecycle (create, update, deactivate, destroy)
BillingOrgAdminService	`/api/admin/billing/v2/orgs`	Billing org provisioning, suspension, settings, audit logs
InvoiceAdminService	`/api/admin/invoices/v2`	Cross-tenant invoice listing, usage stats
RegulationAdminService	`/api/admin/regulations/v2`	Enable/disable regulations per tenant
CodeListAdminService	`/api/admin/code-lists/v2`	Manage code lists (units, tax categories, payment methods)
CodeItemAdminService	`/api/admin/code-items/v2`	Manage individual code entries within lists

Tenant Management¶

Create a Tenant¶

Provisioning a tenant creates a Zitadel organization (identity) and a billing organization simultaneously. The response includes OIDC client credentials for the tenant's M2M API access.

curl -X POST https://stg-gateway.invora.app/api/admin/identity/v2/tenants \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Acme Corp",
    "adminEmail": "admin@acme.com",
    "currency": "SAR"
  }'

Response:

{
  "tenant": {
    "tenantId": "284732941234567890",
    "displayName": "Acme Corp",
    "zitadelOrgId": "284732941234567890",
    "billingOrgId": "b1c2d3e4-...",
    "status": "TENANT_STATUS_PROVISIONING",
    "createdAt": "2026-04-28T10:00:00Z"
  },
  "clientId": "284732941234567891@invora",
  "clientSecret": "secret-only-shown-once"
}

The clientId and clientSecret are shown once on creation. Store them securely.

grpcurl -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"displayName": "Acme Corp", "adminEmail": "admin@acme.com", "currency": "SAR"}' \
  stg-gateway.invora.app:443 \
  invora.admin.identity.v2.TenantAdminService/CreateTenant

List Tenants¶

Supports structured filtering by status, creation date, and text search.

curl -X POST https://stg-gateway.invora.app/api/admin/identity/v2/tenants/list \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "textSearch": "acme",
      "part": {
        "status": {
          "inValues": ["TENANT_STATUS_ACTIVE"]
        }
      }
    },
    "pagination": {"limit": 20}
  }'

Get Tenant¶

curl https://stg-gateway.invora.app/api/admin/identity/v2/tenants/{tenant_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Deactivate / Reactivate¶

Deactivation disables sign-in but preserves all data. Reactivation restores access.

# Deactivate
curl -X POST https://stg-gateway.invora.app/api/admin/identity/v2/tenants/{tenant_id}/deactivate \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Non-payment"}'

# Reactivate
curl -X POST https://stg-gateway.invora.app/api/admin/identity/v2/tenants/{tenant_id}/reactivate \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Destroy Tenant¶

Permanent deletion. Cascades to Zitadel org and billing org.

curl -X DELETE https://stg-gateway.invora.app/api/admin/identity/v2/tenants/{tenant_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Billing Organization Management¶

Provision a Billing Org¶

Normally auto-provisioned during tenant creation. Use this for manual provisioning.

curl -X POST https://stg-gateway.invora.app/api/admin/billing/v2/orgs \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "284732941234567890",
    "displayName": "Acme Corp Billing",
    "currency": "SAR"
  }'

Suspend / Reactivate Billing Org¶

# Suspend (reversible)
curl -X POST https://stg-gateway.invora.app/api/admin/billing/v2/orgs/{tenant_id}/suspend \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Account review"}'

# Reactivate
curl -X POST https://stg-gateway.invora.app/api/admin/billing/v2/orgs/{tenant_id}/reactivate \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Update Org Settings¶

Configure billing defaults for a tenant: currency, timezone, document numbering, grace period, payment terms, email notifications.

curl -X PUT https://stg-gateway.invora.app/api/admin/billing/v2/orgs/{tenant_id}/settings \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "defaultCurrency": "CURRENCY_ENUM_SAR",
      "timezone": "TIMEZONE_TZ_ASIA_RIYADH",
      "documentNumbering": "BILLING_ENTITY_DOCUMENT_NUMBERING_PER_BILLING_ENTITY",
      "invoiceFooter": "Thank you for your business",
      "gracePeriod": 3,
      "locale": "ar",
      "netPaymentTerm": 30,
      "finalizeZeroAmountInvoice": false,
      "emailSettings": {
        "invoiceFinalized": true,
        "creditNoteCreated": true,
        "paymentReceipt": true
      }
    }
  }'

Audit Logs¶

View activity and API request logs for a billing organization.

# Activity logs (who did what)
curl "https://stg-gateway.invora.app/api/admin/billing/v2/orgs/{tenant_id}/activity-logs?pagination.limit=20" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# API request logs (what was called)
curl "https://stg-gateway.invora.app/api/admin/billing/v2/orgs/{tenant_id}/api-logs?pagination.limit=20" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Regulation Configuration¶

Enable a Regulation¶

Each tenant can have multiple regulations enabled (e.g., ZATCA for Saudi Arabia, ETA for Egypt).

curl -X POST https://stg-gateway.invora.app/api/admin/regulations/v2/tenants/{tenant_id}/enable \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "regulationId": "zatca",
    "config": {
      "zatca": {
        "environment": "ZATCA_ENVIRONMENT_PHASE2_SANDBOX",
        "vatRegistrationNumber": "300000000000003",
        "buildingNumber": "1234",
        "autoReportSimplified": true,
        "autoClearStandard": true
      }
    }
  }'

grpcurl -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "tenantId": "284732941234567890",
    "regulationId": "zatca",
    "config": {"zatca": {"environment": "ZATCA_ENVIRONMENT_PHASE2_SANDBOX"}}
  }' \
  stg-gateway.invora.app:443 \
  invora.admin.regulations.v2.RegulationAdminService/EnableRegulation

Update Regulation Config¶

curl -X PUT https://stg-gateway.invora.app/api/admin/regulations/v2/tenants/{tenant_id}/regulations/zatca \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "zatca": {
        "environment": "ZATCA_ENVIRONMENT_PHASE2_PRODUCTION",
        "vatRegistrationNumber": "300000000000003",
        "autoClearStandard": true
      }
    }
  }'

List Tenant Regulations¶

curl https://stg-gateway.invora.app/api/admin/regulations/v2/tenants/{tenant_id}/regulations \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Disable a Regulation¶

curl -X POST https://stg-gateway.invora.app/api/admin/regulations/v2/tenants/{tenant_id}/disable \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"regulationId": "zatca"}'

Cross-Tenant Invoice Management¶

List All Invoices¶

View invoices across all tenants with filtering.

curl -X POST https://stg-gateway.invora.app/api/admin/invoices/v2/list \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "part": {
        "status": {
          "inValues": ["INVOICE_STATUS_TYPE_FINALIZED"]
        }
      }
    },
    "pagination": {"limit": 50}
  }'

Tenant Usage Stats¶

Get aggregated usage statistics for a tenant over a time range.

curl "https://stg-gateway.invora.app/api/admin/invoices/v2/tenants/{tenant_id}/usage-stats?from=2026-01-01T00:00:00Z&to=2026-04-28T23:59:59Z" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Platform Enrollment Review¶

Admins review platform upgrade applications submitted by business-tier tenants.

List Applications¶

curl -X POST https://stg-gateway.invora.app/api/admin/identity/v2/platform-applications/list \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "part": {
        "status": {
          "inValues": ["PLATFORM_APPLICATION_STATUS_PENDING"]
        }
      }
    },
    "pagination": {"limit": 20}
  }'

Review an Application¶

curl -X POST https://stg-gateway.invora.app/api/admin/identity/v2/platform-applications/{application_id}/review \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "PLATFORM_APPLICATION_DECISION_APPROVE",
    "reviewNotes": "Business verified, approved for platform tier"
  }'

Decisions: APPROVE, REJECT, or REQUEST_INFO. Notes are required for reject and request_info.

Code List & Code Item Management¶

Platform administrators manage the standardized code lists used across all tenants' documents — units of measure, tax categories, payment methods, country codes, and more. Tenants have read-only access.

Create a Code List¶

curl -X POST https://gateway.invora.app/api/admin/code-lists/v2 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "changes": {
      "name": {"values": [{"locale": "en", "value": "Unit of Measure"}]},
      "description": "UN/ECE Recommendation 20 unit codes"
    }
  }'

Add Code Items to a List¶

curl -X POST https://gateway.invora.app/api/admin/code-items/v2 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "changes": {
      "codeListKey": "uom",
      "code": "EA",
      "name": {"values": [{"locale": "en", "value": "Each"}]},
      "description": "Individual unit"
    }
  }'

Update and Delete¶

# Update a code item
curl -X PUT https://gateway.invora.app/api/admin/code-items/v2/{key} \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"concurrencyStamp": "<stamp>", "changes": {"description": "Updated description"}}'

# Delete code items
curl -X POST https://gateway.invora.app/api/admin/code-items/v2/delete \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["item-key-1", "item-key-2"]}'

Tenants access these code lists via the read-only CodeListsService and CodeItemsService in the invoicing module.

Authentication¶

All admin endpoints use the same JWT authentication as other Invora APIs. See the Authentication Guide for setup. Admin scopes are granted via Zitadel role assignments to platform administrator users.