> For the complete documentation index, see [llms.txt](https://developer.vario-software.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.vario-software.de/app-store-guidelines/app-requirements/permissions-and-data-quality.md).

# Permissions and Data Quality

Permission, tenant isolation, and data integrity requirements for VARIO App Store apps.

A Public App must access only the VARIO data and functionality it actually requires and must preserve the integrity of customer data throughout processing, synchronization, and automation.

This page defines the review requirements for VARIO permissions, app-specific authorization, tenant separation, data mapping, synchronization, and duplicate prevention.

{% hint style="info" %}
Technical permission syntax and available resources are documented in the [App Manifest](https://developer.vario-software.de/documentation/apps/app-manifest) and the corresponding API documentation.

This page defines how those permissions and data accesses are evaluated during App Store review.
{% endhint %}

### Request only required VARIO permissions

The app must follow the principle of least privilege.

It may request only the VARIO permissions required for functionality that is actually available in the submitted version.

Permissions must not be requested:

* for functionality that is only planned for the future;
* as a precaution in case they may become useful later;
* for data that is unrelated to the app's documented purpose;
* where a less extensive permission is sufficient for the same functionality.

VARIO permissions are defined by a combination of resource and operation, for example:

```
crm-activity:read
crm-activity:create
```

The exact permission model is documented in the [App Manifest](https://developer.vario-software.de/documentation/apps/app-manifest).

{% hint style="warning" %}
Requesting broad access without a clear functional reason may prevent approval even if the app does not currently use that access.
{% endhint %}

### Explain requested permissions

As part of the review submission, the App Provider must be able to explain the purpose of each requested VARIO permission.

For each permission, VARIO may ask:

* which app function requires it;
* which VARIO data is accessed;
* whether the app reads, creates, updates, or deletes data;
* whether access occurs through a user action or automatically in the background;
* whether the permission is required for all customers or only for an optional feature.

The explanation should be specific enough for VARIO to understand the relationship between the requested access and the advertised functionality.

For example:

{% columns %}
{% column %}

#### Too broad

> The app needs access to customers because it integrates with VARIO.
> {% endcolumn %}

{% column %}

#### Better

> `account:read` is required to transfer the customer's billing address and external customer number when creating a shipment in the connected service.
> {% endcolumn %}
> {% endcolumns %}

### Permission changes

Adding or extending VARIO permissions after an app has been approved is considered a relevant change.

New permissions must not be introduced solely through an unnoticed manifest update.

Changes to the required permission scope must be communicated to VARIO and may require another review.

See **App Updates and Re-Review** for the applicable process.

### App-specific authorization

Apps may define their own authorization verbs to control which VARIO users are allowed to access app functions.

App-specific permissions must:

* use understandable names and descriptions;
* correspond to actual app functionality;
* restrict sensitive actions where appropriate;
* be applied consistently throughout the app.

A permission must not only hide a button or navigation item in the user interface.

If an action requires an app-specific authorization, the app must also prevent unauthorized execution at the technical level.

{% hint style="danger" %}
Hiding an action in the frontend is not an authorization mechanism.

A user must not be able to execute a restricted action simply by calling its URL or backend endpoint directly.
{% endhint %}

### Tenant isolation

Every installation of an app belongs to a specific VARIO Cloud tenant.

The app must reliably separate:

* credentials;
* configuration;
* customer data;
* background jobs;
* Webhook processing;
* external system connections

between different tenant installations.

A request or background process belonging to one tenant must never read, modify, transmit, or expose data belonging to another tenant.

Tenant context must be determined from trusted authentication or installation information and must not rely solely on a tenant identifier supplied by the frontend.

Where credentials such as the `offlineToken` are stored, they must be associated with the correct tenant and must not be shared between installations.

For authentication details, refer to [App Authentication](https://developer.vario-software.de/documentation/apps/authentication).

### Access only the data required for the process

Even where a permission technically allows access to a larger dataset, the app should retrieve only the information required for its current purpose.

For example, an app should:

* select only required fields where practical;
* apply appropriate filters;
* avoid exporting complete datasets where a limited subset is sufficient;
* avoid retaining VARIO data that is no longer required for the app's functionality.

This improves both data protection and technical efficiency.

### Preserve business meaning

Apps exchanging data between VARIO and another system must preserve the business meaning of the data.

Mappings must correctly handle relevant attributes such as:

* identifiers;
* quantities and units;
* currencies;
* prices and tax-relevant values;
* dates and timestamps;
* time zones;
* status values;
* references between business objects;
* country and language codes.

The app must not silently reinterpret, truncate, round, merge, or discard relevant information in a way that can change the intended business result.

Where the target system cannot represent a VARIO value without loss, the behavior must be documented or made visible to the user.

### Use stable identifiers

Where records are synchronized between VARIO and another system, the app must use identifiers that allow records to be matched reliably over time.

Display names, descriptions, positions in a list, or other values that users can freely change should not be used as the sole identifier for synchronization.

Where appropriate, the app should maintain a mapping between:

* the VARIO record identifier; and
* the corresponding identifier in the external system.

The mapping must be tenant-specific.

### Define synchronization ownership

For bidirectional or recurring synchronization, it must be clear which system is authoritative for the relevant data.

The app must define predictable behavior when the same information has changed in both systems.

Depending on the use case, this may mean:

* VARIO is authoritative;
* the external system is authoritative;
* the most recent change wins;
* the user must resolve the conflict.

The chosen behavior must not result in unpredictable overwriting of customer data.

If relevant to normal operation, the synchronization direction and important conflict rules must be documented for the customer.

### Prevent unintended duplicates

Apps must assume that technical events and requests can occur more than once.

VARIO Webhooks use at-least-once delivery semantics and therefore may be delivered repeatedly. They are not guaranteed to arrive in chronological order.

For implementation details, refer to [Webhooks](https://developer.vario-software.de/documentation/webhooks/introduction).

Apps must therefore make relevant processing idempotent or otherwise protect against unintended duplicate processing.

A repeated event, retry, or synchronization run must not unintentionally create another:

* customer;
* article;
* order;
* delivery;
* invoice;
* payment;
* inventory transaction;
* external platform object;
* comparable business record.

{% hint style="warning" %}
A Webhook being received twice is not an exceptional situation. Apps must be designed so that repeated delivery does not create duplicate business transactions.
{% endhint %}

Where strict idempotency is technically not possible, the app must provide another reliable mechanism for detecting and handling duplicates.

### Handle event ordering

Apps must not assume that Webhooks or asynchronous events are received in exactly the same order in which the underlying business changes occurred.

Where sequence matters, the app must determine the current state of the affected object before applying an irreversible action.

The current state in VARIO or the external system should take precedence over assumptions based solely on event arrival order.

### Imports and create-or-update logic

When importing data, the app must determine whether an incoming record represents:

* a new business object;
* an update to an existing business object;
* a record that should be ignored;
* a conflict requiring intervention.

The matching criteria must be deterministic.

An import must not create a new VARIO record on every run merely because no reliable matching strategy has been implemented.

Where the app performs recurring imports, running the same input again should produce a predictable result.

### Complete and reliable pagination

Where larger datasets are retrieved in multiple pages or batches, the app must ensure that processing does not unintentionally:

* skip records;
* process the same records multiple times;
* terminate before all intended records have been processed.

The app must use the pagination and filtering mechanisms provided by the relevant VARIO interface.

Where the result set can change during processing, the app must use an appropriate strategy to maintain a stable and predictable result.

See [Pagination and Filtering](https://developer.vario-software.de/documentation/rest-api/pagination-and-filtering) and [VQL](https://developer.vario-software.de/documentation/fundamentals/vql).

### Validate data before writing

Data received from external systems must not be written blindly into VARIO.

Before creating or modifying business data, the app must validate information that is relevant to the operation.

Depending on the use case, this may include:

* required fields;
* data types;
* valid references;
* quantities;
* amounts;
* currencies;
* country or language codes;
* supported status values;
* required mappings.

Invalid data must result in a controlled error instead of silently creating incorrect or incomplete business data.

### Partial processing

Where an operation processes multiple records, the app must handle partial failures explicitly.

It must be possible to determine which records:

* completed successfully;
* failed;
* were not processed.

Successfully processed records must not automatically be processed again merely because another record in the same batch failed, unless the complete operation is intentionally transactional.

The customer must not be presented with a fully successful result when only part of the operation completed.

### Retries

Temporary failures may be retried automatically where appropriate.

Retry behavior must be controlled.

The app must avoid:

* unlimited retry loops;
* retries at excessively short intervals;
* duplicate business operations caused by a retry;
* repeatedly processing permanently invalid data.

Where a failure requires user action, the app should stop automated retries and make the problem visible.

### Background processing status

Customer-relevant automated processes must provide sufficient visibility into their status.

Where appropriate, the app should distinguish between states such as:

* queued;
* processing;
* completed;
* failed.

For failed operations, the user should be able to understand:

* which operation failed;
* which business object was affected;
* whether data has already been partially processed;
* what action can be taken next.

A technical server log available only to the App Provider is not sufficient as the sole status information for a customer-facing business process.

### Retry actions

Where a failed operation can safely be retried by the user, the app should provide an appropriate retry mechanism.

The retry must continue from a known state and must not recreate business objects that were successfully created during the previous attempt.

If manual correction is required before retrying, the app should explain what needs to be corrected.

### Destructive and high-impact data operations

Operations that delete, overwrite, or change a significant amount of business data require additional care.

The app must make the effect of such an operation clear before it is executed.

Depending on the risk, an appropriate safeguard may include:

* a confirmation step;
* a summary of affected records;
* a preview;
* validation before execution;
* an operation log;
* a controlled recovery or correction process.

Detailed requirements for user interaction and confirmation are covered in **User Experience and Design**.

### Error information must not expose sensitive data

Logs and error information used to diagnose data-processing problems must not unnecessarily expose:

* access tokens;
* API keys;
* passwords;
* confidential request headers;
* complete customer payloads where they are not required;
* personal data unrelated to troubleshooting.

If technical request or response information is made visible to users or stored for troubleshooting, sensitive values must be masked where appropriate.

Security-specific requirements are covered in **Security and Privacy Review**.

### What VARIO reviews

During the permissions and data quality review, VARIO may verify in particular whether:

* requested VARIO permissions are necessary for the advertised functionality;
* requested permissions can be clearly explained;
* app-specific permissions restrict actual backend functionality and not only the UI;
* tenant data and credentials are reliably separated;
* the app accesses only data relevant to its purpose;
* mappings preserve the business meaning of VARIO data;
* records can be matched reliably between systems;
* synchronization behavior is predictable;
* repeated Webhooks or retries do not create unintended duplicates;
* imports distinguish between new and existing records;
* pagination processes the intended dataset completely;
* invalid data is handled before it creates incorrect business records;
* partial failures and retry behavior are transparent;
* customer-relevant background processes expose an understandable status;
* high-impact data operations include appropriate safeguards.

VARIO may test additional scenarios depending on the type of data processed and the impact of the app on customer business processes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.vario-software.de/app-store-guidelines/app-requirements/permissions-and-data-quality.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.