FAQ

Frequently asked questions about App authentication, installation, migrations, manifests and UI integrations.

App authentication

Where does my App get its credentials for a tenant?

VARIO Cloud hands your App an offlineToken in the body of the install call. Persist it, keyed by tenant, before doing anything else. Your App exchanges it for short-lived access tokens from then on.

It is not a one-time-only event, though: the customer can renew it at any time. In the Admin-Center, on the installed App's page, "Offline-Token erneuern" issues a fresh offlineToken and calls your install endpoint again with it.

So your install endpoint must be safe to call more than once, and must overwrite the stored token rather than keeping the first one. Migrations already behave that way — a step that has run is skipped — but the token write must not be conditional on "no token stored yet".

→ App Authentication

My App suddenly gets 401 from the API for one tenant. Why?

Most likely the tenant's offlineToken has expired through inactivity.

The token is valid for 45 days, and every use extends it by another 45. So it never expires while the App is working — but 45 consecutive days with no API call for that tenant invalidate it. Typical victims: seasonal integrations, test tenants, and Apps that only act when a customer triggers something.

Once it has expired, the App instance is flagged accordingly and the customer is prompted in the Admin-Center to use "Offline-Token erneuern", which sends your install endpoint a fresh token. That is a customer action — your App cannot trigger it.

Two things you can do:

• Prevent it: if your App can be idle for weeks, make a small scheduled call so the token stays alive.
• Diagnose it: fail clearly and log which tenant is affected, so this looks like an expired token rather than a generic outage.

VARIO calls my App and my App answers 401. What's wrong?

Your App is rejecting the inbound token. It must be verified as:

• an ES256-signed JWT,
• against the JWK set you received when creating the App,
• with aud equal to your appIdentifier,
• and a valid exp.

Installation and migrations

I changed my migration and nothing happened.

Migrations run once, ever. Each step is recorded by name, and an already-recorded step is skipped — editing its body has no effect on tenants where it already ran.

Add a new step with a new name instead. For steps that must run every time (webhook registration is the classic case), use always() rather than setMigration().

My install reported success but nothing was created.

Migration errors are caught, not thrown: they go to your error handler and the app log, and the install still reports success.

Read the app log. Failed steps are not recorded as completed, so they retry on the next install.

createSalesChannel returned an empty object.

That is the platform telling you a license is missing. Only the first sales channel is license-free; creating more requires a sales channel license. The framework catches the resulting 402, logs a warning and returns {} so the migration continues — which means your code must tolerate a missing id.

I get a 404 reading an EAV group that I create in the same migration.

Ordering. An EAV group must be created by an earlier step before it can be read or changed. The same applies to anything else you look up by identity — a bank cannot reference a backend that doesn't exist yet.

Manifest, permissions and UI

What is the complete list of pointOfIntegration values?

There intentionally isn't one in this documentation — integration points are added with every release, so any list published here would be wrong within a version or two.

Read them out of your own installation instead:

1. Open the ERP in support mode.
2. Enable the toggle "App-Integrationspunkte anzeigen" ("Show app integration points").
3. Reload when prompted.

Every available integration point is now labelled in the UI with the exact pointOfIntegration string to put in your manifest. Navigate to the screen you want to extend and read it off there.

→ App Manifest

My UI integration doesn't show up.

There is no manifest validation, and integration points are matched by exact string comparison — so a typo means your integration silently never appears.

Check:

• the spelling of pointOfIntegration;
• that you kept the literal {APP_IDENTIFIER} placeholder where the point requires it;
• that the user has the verb named in permissionKey.

Integration points are added with every release, so don't work from a list. Open the ERP in support mode, enable "App-Integrationspunkte anzeigen" and reload — the ERP then labels every available integration point with the exact pointOfIntegration string to use.

→ App Manifest