External Forms — Developer Integration Guide

External Forms allow external web applications to be embedded directly into KORONA Studio as part of the system’s navigation. This enables partners and solution providers to build custom UI modules that interact with the customer’s KORONA account data using the KORONA APIv3.

When the user opens the External Form inside KORONA Studio, the configured URL is loaded inside an iframe. KORONA automatically appends authentication and context parameters so the embedded application can authenticate and communicate with the KORONA API securely.

1. Configuration in KORONA Studio

Path: Settings → External Forms

Each External Form has the following configuration fields:

Field	Description
Number	Internal identifier of the form.
Name	Display name shown in the navigation and browser tab.
Display URL	Base URL of the external application (KORONA will append parameters).
Navigation Category	Where the menu item appears (e.g., Inventory, Reports, Sales).
User Roles	Which user roles may access the form (Master users always see it).

Once saved, KORONA automatically creates a dedicated APIv3 user for this form if one does not already exist.
This API user is used solely by the external form to authenticate API requests.

2. How the Form is Displayed

When the user clicks the menu entry, KORONA:

Opens a new tab in Studio.
Loads the configured Display URL inside an iframe.
Appends authentication & context as base64-encoded query parameters.

Example request:

https://your-app.example.com/your-ui-page?
  accountId=ZjM1ZTdlM2YtMDg0ZC00NDBkLTlkZmMtMWFkNzU3NTM3MzE1&
  apiUserLogin=ZXh0ZXJuYWxfZm9ybQ%3D%3D&
  apiUserPassword=dbno6jb9da38en47kz3vftd4p&
  url=aHR0cHM6Ly90cnVuay50ZXN0LmNvbWJhc2UuZGUvd2ViLw%3D%3D&
  locale=en

3. Passed Query Parameters

Parameter	Encoded	Meaning	Notes
`accountId`	Base64	UUID of the KORONA Account	Use in API requests.
`apiUserLogin`	Base64	Login of the dedicated API user	Use for HTTP Basic auth.
`apiUserPassword`	Base64	Password of the dedicated API user	Use for HTTP Basic auth.
`url`	Base64	Base URL of the current KORONA Studio instance	Useful for redirects and links.
`locale`	Plaintext	User’s language selection (`de`, `en`, `es`, etc.)	Use for UI localization.

All values except locale must be base64-decoded before use.

4. Authentication Against the API

The KORONA APIv3 uses HTTP Basic Authentication:

Authorization: Basic base64(apiUserLogin:apiUserPassword)

Example (pseudo-code):

const login = atob(apiUserLogin);        // base64 decode
const password = atob(apiUserPassword);

const authHeader = "Basic " + btoa(`${login}:${password}`);

5. Calling the API

Example: Fetch cashiers of the account

GET {studioBaseUrl}/api/v3/accounts/{accountId}/cashiers
Accept: application/json
Authorization: Basic <base64(login:password)>

Example response will contain JSON data representing cashiers in the account.

6. UI / IFrame Considerations

Your external app:

Must support being embedded in an iframe.
Should automatically adapt to fullscreen content.
Should respect the locale parameter for UI language.
Should handle session refresh/reload gracefully.

7. Security Notes

Each External Form uses a dedicated API user, isolated per form.
This avoids exposing admin credentials.
If the External Form entry is removed, the navigation updates immediately and the API user is removed.
Your app should never store the API credentials permanently.
They are passed on every access and can change.

8. Example: Minimal JavaScript Client

const params = new URLSearchParams(window.location.search);

const accountId = atob(params.get("accountId"));
const login = atob(params.get("apiUserLogin"));
const password = atob(params.get("apiUserPassword"));
const studioUrl = atob(params.get("url"));
const locale = params.get("locale");

async function fetchAccountData() {
  const res = await fetch(`${studioUrl}api/v3/accounts/${accountId}`, {
    headers: {
      "Accept": "application/json",
      "Authorization": "Basic " + btoa(`${login}:${password}`)
    }
  });
  return res.json();
}

fetchAccountData().then(console.log);

9. Best Practices

Topic	Recommendation
Authentication	Always generate Authorization header dynamically.
UI Language	Use `locale` to load translations.
Error Handling	Display meaningful API errors to the user.
Logging	Log to your server, not to browser console.

10. Support

If you need help building or testing your external form integration, contact us.

11. List your External Form in the KORONA AppCenter

The KORONA AppCenter lists integration options and enables “one-click” setup inside KORONA Studio. The AppCenter is available at appcenter.koronacloud.com.

If your integration is an External Form (embedded UI page in Studio), we can publish it in the AppCenter so customers can add it without manually creating an External Form entry in Studio. (External Forms are loaded in an iframe and receive the authentication/context parameters described above.)

What you need to provide

To be listed in the AppCenter, provide:

Studio URL (Display URL)
- The HTTPS URL that should be embedded in Studio (this is the “Display URL” used by External Forms). KORONA Studio will append the parameters described in this guide (e.g., accountId, apiUserLogin, apiUserPassword, url, locale).
- Your application must support being loaded in an iframe.
App logo
- A square logo file (recommended) that represents your app (shown in the AppCenter app listing).
App description
- Short description of what the app does and what it adds/creates in KORONA Studio (the AppCenter shows an app “Description” and what it can create in Studio).
Developer contact information
- Company name and support contact (the AppCenter displays “Developer Contact Information”).

Submission

Submit your app via the developer form at koronapos.com/developers/.

In your submission, include the items above (URL, logo, description, developer contact). Once approved, the AppCenter entry will allow customers to add the integration to their Studio with a single click.