Identity API Guide¶

The Identity API handles everything a business needs to get started on Invora: creating an account, completing onboarding, choosing a plan, and -- for platforms -- managing connected businesses underneath them.

This guide covers the two public-facing services:

PublicRegistrationService -- self-service registration and onboarding
ConnectedBusinessService -- creating and managing sub-businesses (for platform accounts)

A separate admin-only service exists for Invora staff to manage tenants and review platform applications. It is not covered here.

Core Concepts¶

Organization Types¶

Every business on Invora is one of three types:

Type	Description
Business	A standalone company using Invora for e-invoicing, billing, or both.
Platform	A company that also manages other businesses underneath it (reseller, SaaS provider, franchisor, aggregator).
Connected Business	A sub-business created and managed by a Platform. Inherits the platform's billing relationship -- usage rolls up to the parent.

A Business can later apply to become a Platform. A Connected Business is always created by its parent Platform.

Capabilities¶

When registering, a business declares which Invora capabilities it wants to use:

Capability	What It Enables
E-Invoicing	Create, validate, and submit electronic invoices compliant with local regulations (ZATCA, Peppol, etc.).
Billing	Subscription management, usage metering, recurring invoicing, and payment collection.

A business can enable one or both. Capabilities can be changed later.

Onboarding Checklist¶

Invora tracks onboarding progress as a checklist. Each step has a key, a human-readable title, and a completion flag. The checklist also reports an overall completionRatio (0.0 to 1.0) so you can render a progress bar.

The checklist is returned from most registration endpoints, so your UI always has the latest state without a separate fetch.

Onboarding Flow¶

A new business goes through these steps:

flowchart TD
  A["1. Create Account<br/>(your auth UI — outside Invora API)"]
  B["2. Complete Profile<br/>POST /api/identity/v2/registration/complete-profile"]
  C["3. Business Details<br/>PUT /api/identity/v2/registration/business-details<br/>(optional, can defer)"]
  D["4. Select Plan<br/>POST /api/identity/v2/registration/select-plan"]
  E["Done — business is active"]
  A --> B --> C --> D --> E

Step 1: Create Account¶

The user creates an account through Invora's authentication system (hosted login page or your embedded auth flow). This gives them a valid access token but no business profile yet.

Step 2: Complete Business Profile¶

The first API call a new user makes. Provide:

businessName -- the display name for the company
country -- ISO 3166-1 alpha-2 code (e.g., "SA" for Saudi Arabia, "EG" for Egypt)
capabilities -- which Invora features to enable (EINVOICING, BILLING, or both)

The response includes:

tenantId -- your organization's unique identifier, used across all Invora APIs
clientId and clientSecret -- OIDC credentials for machine-to-machine API access (server-to-server integrations).
checklist -- current onboarding progress

Warning

The clientSecret is only returned once at creation time. Store it in a secure vault immediately. It cannot be retrieved again.

POST /api/identity/v2/registration/complete-profile HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "businessName": "Acme Trading Co.",
  "country": "SA",
  "capabilities": ["BUSINESS_CAPABILITY_EINVOICING", "BUSINESS_CAPABILITY_BILLING"]
}

Step 3: Update Business Details (Optional)¶

Fill in tax and address information. This step supports progressive profiling -- you can call it during onboarding or let the user complete it later from settings.

Fields:

taxId -- tax identification number (e.g., VAT number)
addressLine, city, postalCode, country -- business address
currency -- ISO 4217 code (e.g., "SAR", "EGP", "USD")
timezone -- IANA timezone (e.g., "Asia/Riyadh")

PUT /api/identity/v2/registration/business-details HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "taxId": "300000000000003",
  "addressLine": "King Fahd Road",
  "city": "Riyadh",
  "postalCode": "11564",
  "country": "SA",
  "currency": "SAR",
  "timezone": "Asia/Riyadh"
}

Step 4: Select a Plan¶

Choose a subscription plan. Available plans can be retrieved from the Account API (not covered here). Pass the plan code:

POST /api/identity/v2/registration/select-plan HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "planCode": "starter-monthly"
}

The response includes the new subscriptionId and updated checklist.

Checking Onboarding Status¶

At any point, call GetOnboardingStatus to see where the business stands:

GET /api/identity/v2/registration/onboarding-status HTTP/1.1
Authorization: Bearer <access_token>

Returns the tenantId, organization type, and the full onboarding checklist.

Connected Businesses¶

Connected Businesses are the foundation of Invora's platform and reseller model. If your business manages other businesses -- as a reseller, franchise network, SaaS platform, or aggregator -- you create each of those businesses as a Connected Business under your account.

Why Connected Businesses?¶

Centralized billing. Usage from all Connected Businesses rolls up to the parent platform's billing account. The parent pays one bill; sub-businesses do not need separate payment methods.
Centralized management. The parent platform can create, suspend, and reactivate Connected Businesses through the API.
Isolated data. Each Connected Business is a fully separate tenant with its own users, invoices, and documents. The parent can manage the lifecycle but data stays isolated.
Plan-gated limits. The number of Connected Businesses you can create depends on your plan. If you exceed the limit, creation fails with a RESOURCE_EXHAUSTED error.

Becoming a Platform¶

Only Platform-tier organizations can create Connected Businesses. A standard Business account can apply for Platform status through the platform enrollment flow. This application is reviewed by Invora before approval.

Creating a Connected Business¶

POST /api/v2/identity/connected-businesses HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "Acme Riyadh Branch",
  "country": "SA",
  "taxId": "300000000000004",
  "adminEmail": "admin@acme-riyadh.com"
}

The response includes:

connectedBusiness -- the new tenant record with its tenantId, parentTenantId, country, tax ID, and timestamps
clientId and clientSecret -- OIDC credentials for the Connected Business's own API access.

Warning

The clientSecret is only returned once at creation time. Store it in a secure vault immediately. It cannot be retrieved again.

Listing Connected Businesses¶

Retrieve all Connected Businesses under your organization. Supports pagination and text search.

POST /api/v2/identity/connected-businesses/list HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "textSearch": "riyadh",
  "pagination": {
    "limit": 20
  }
}

Getting a Connected Business¶

GET /api/v2/identity/connected-businesses/{tenantId} HTTP/1.1
Authorization: Bearer <access_token>

Suspending a Connected Business¶

Suspending a Connected Business revokes its users' access and pauses billing. Data is preserved. Provide a reason for audit purposes.

POST /api/v2/identity/connected-businesses/{tenantId}/suspend HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "reason": "Non-payment"
}

Reactivating a Connected Business¶

Restores access and resumes billing for a previously suspended Connected Business.

POST /api/v2/identity/connected-businesses/{tenantId}/reactivate HTTP/1.1
Authorization: Bearer <access_token>

Platform Enrollment¶

To upgrade from a standard Business to a Platform (enabling Connected Business management), a business submits a platform enrollment application. The application includes:

Why the business needs platform capabilities
Expected number of Connected Businesses
Expected monthly transaction volume
Technical contact email
Terms of service acceptance

Applications are reviewed by Invora. Possible outcomes:

Decision	Effect
Approved	Organization is upgraded to Platform type. Connected Business endpoints become available.
Rejected	Organization remains a Business. The rejection reason is provided.
Info Requested	Invora needs more information before deciding. The business can update and resubmit.

RPC Reference¶

PublicRegistrationService¶

All endpoints require a valid access token from a signed-in user. No admin privileges needed.

RPC	Method	Path	Description
`CompleteBusinessProfile`	POST	`/api/identity/v2/registration/complete-profile`	Create the business organization after account signup. Sets the business name, country, and desired capabilities. Returns the tenant ID and machine-to-machine API credentials (client ID + secret). This is the first call a new user makes.
`UpdateBusinessDetails`	PUT	`/api/identity/v2/registration/business-details`	Add or update tax, address, currency, and timezone details. Supports progressive profiling -- can be called during onboarding or deferred to later.
`SelectPlan`	POST	`/api/identity/v2/registration/select-plan`	Subscribe the business to a billing plan. Returns the subscription ID. Plan codes are available from the Account API.
`GetOnboardingStatus`	GET	`/api/identity/v2/registration/onboarding-status`	Returns the current onboarding checklist with completion status for each step and overall progress ratio. Use this to render an onboarding progress UI.

ConnectedBusinessService¶

All endpoints require Platform-tier authorization. The exact permissions depend on your plan and role configuration.

RPC	Method	Path	Description
`CreateConnectedBusiness`	POST	`/api/v2/identity/connected-businesses`	Create a new sub-business under your organization. Provide the business name, country, tax ID, and an admin email. Returns the new tenant record and its API credentials. Fails with `RESOURCE_EXHAUSTED` if your plan's Connected Business limit is reached.
`ListConnectedBusinesses`	POST	`/api/v2/identity/connected-businesses/list`	List all Connected Businesses under your organization. Supports cursor-based pagination and text search across business names.
`GetConnectedBusiness`	GET	`/api/v2/identity/connected-businesses/{tenantId}`	Retrieve details of a specific Connected Business including its status, country, tax ID, and timestamps.
`SuspendConnectedBusiness`	POST	`/api/v2/identity/connected-businesses/{tenantId}/suspend`	Suspend a Connected Business. Revokes user access and pauses billing. Requires a reason for the audit trail. Data is preserved and the business can be reactivated.
`ReactivateConnectedBusiness`	POST	`/api/v2/identity/connected-businesses/{tenantId}/reactivate`	Restore a suspended Connected Business. Re-enables user access and resumes billing.

Common Patterns¶

Machine-to-Machine Access¶

Both CompleteBusinessProfile and CreateConnectedBusiness return OIDC clientId and clientSecret values. These are for server-to-server API access (background jobs, integrations, webhooks).

Warning

The clientSecret is only returned once at creation time. Store it in a secure vault immediately. If lost, rotate credentials via RotateCredentials through the account settings.

Pagination¶

List endpoints use cursor-based pagination. Pass a limit in the pagination field. If more results exist, the response includes a nextPageCursor -- pass it as cursor in the next request.

Error Handling¶

gRPC Code	HTTP Status	Meaning
`ALREADY_EXISTS`	409	Business profile already completed, or Connected Business with that name already exists.
`RESOURCE_EXHAUSTED`	429	Connected Business limit for your plan has been reached. Upgrade your plan or remove unused businesses.
`PERMISSION_DENIED`	403	Your account does not have the required plan or role for this operation.
`NOT_FOUND`	404	The specified tenant ID does not exist or is not under your organization.
`INVALID_ARGUMENT`	400	Missing or invalid field values (e.g., invalid country code, empty business name).