> 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/documentation/apps/authentication.md).

# Authentication

### Authenticating with OAuth 2.0 using the VARIO App Framework

When you build your own Node.js backend (not using the demo app repository), you can still use the **VARIO App Framework backend package** to handle authentication for you.

At a high level:

* Your app **stores** the VARIO Cloud credentials and refresh tokens.
* The **framework backend** handles:
  * OAuth 2.0 *refresh token* grant
  * obtaining and caching access tokens
  * adding `Authorization: Bearer <access_token>` to all VARIO API calls ([GitHub](https://github.com/vario-software/vario-app-framework?utm_source=chatgpt.com))

You never have to call the token endpoint manually.

***

#### 1. What you need before you start

To authenticate via the framework backend you need:

1. **App credentials (AppClient)** from the VARIO-Cloud Admin Center\
   (see *“Creating a new App and getting API credentials”*):
   * `appIdentifier`
   * `clientId`
   * `clientSecret`
2. **One refresh token per VARIO-Cloud installation**
   * Obtained once during the installation/authorization flow of your app (e.g. on your `pcInstallationUrl`).
   * Stored securely in your own database or configuration.
3. **Base URLs for your environment**
   * VARIO Cloud API base URL (business API)
   * OAuth 2.0 token endpoint URL

The framework will use `clientId`, `clientSecret`, and the installation-specific `refreshToken` to obtain access tokens via `grant_type=refresh_token`.

***

#### 2. Install the framework backend

In your Node.js backend project:

```
npm install @vario-software/vario-app-framework-backend
```

The backend package is responsible for **API communication and authentication**. ([libraries.io](https://libraries.io/npm/%40vario-software%2Fvario-app-framework-backend?utm_source=chatgpt.com))

> The frontend package (`@vario-software/vario-app-framework-frontend`) is optional here and only relevant for styling/JS helpers in your UI.

***

#### 3. Provide configuration: app client + installations

Your app needs a way to provide two types of data to the framework:

1. **Static app client config** (same for all installations):

   ```
   {
     "appIdentifier": "your-app-identifier",
     "clientId": "your-client-id",
     "clientSecret": "your-client-secret",
     "appJWK": "JWK_TOKEN"
   }
   ```

   You can use an `app-client.json` file (similar to the demo app) or environment variables. The demo app reads this file at startup and passes the values into the framework.
2. **Installation-specific refresh tokens**

   For each customer/tenant installation:

   * You receive a **refresh token** during the app installation/authorization flow.
   * You store it in a database table like `app_installations`:
     * `installation_id`
     * `refresh_token`
     * maybe also tenant-specific URLs / metadata.

***

#### 4. Initialize the framework backend

In your backend, create a module responsible for wiring **your configuration** into the framework.

Example structure:

```
const frameworkApp = /* createBackendApp */({
  appIdentifier: appClient.appIdentifier,
  clientId: appClient.clientId,
  clientSecret: appClient.clientSecret,
  appJWK: appClient.appJWK
  // optional: base URLs, logging, etc.
});

// Helper for your routes: get an authenticated client for a given installation
export async function getVarioClient(installationId: string) {
  const installation = await loadInstallation(installationId);

  // Ask the framework for a client that uses the refresh token
  const client = await frameworkApp.getApiClient({
    installationId,
    refreshToken: installation.refreshToken,
    // Called when the framework receives a rotated refresh token
    onRefreshTokenUpdated: async (newRefreshToken: string) => {
      installation.refreshToken = newRefreshToken;
      await saveInstallation(installation);
    },
  });

  return client; // used to call VARIO APIs
}
```

***

#### 5. Use the framework client in your own routes

Once you have a helper like `getVarioClient(installationId)`, you can use it inside your Express (or Fastify, etc.) route handlers.

Example (pseudo-code with Express):

```
// Example: list activities for a given installation
router.get("/api/activities", async (req, res, next) => {
  try {
    // In a real app you derive the installationId from the session, JWT, subdomain, etc.
    const installationId = req.headers["x-installation-id"] as string;

    const client = await getVarioClient(installationId);

    // The framework client hides OAuth:
    // - it ensures access token exists/is valid (using refresh_token if needed)
    // - it calls the VARIO Cloud API with the correct Authorization header
    const activities = await client.get("/crm-activity", {
      // any query parameters, VQL, etc.
    });

    res.json(activities);
  } catch (err) {
    next(err);
  }
});

export default router;
```

From your app’s perspective:

* You **never** manually:
  * call the OAuth token endpoint
  * build `Authorization` headers
  * check expiry times
* You **always**:
  * ask the framework to give you an API client for an installation
  * call `.get()`, `.post()`, etc. on that client

Under the hood the framework:

1. Reads `clientId` / `clientSecret`.
2. Uses the installation’s `refreshToken` to request an access token (`grant_type=refresh_token`).
3. Caches the access token until it expires.
4. Sends the VARIO-Cloud API request with `Authorization: Bearer <access_token>`.
5. If the OAuth server returns a new `refresh_token`, it calls `onRefreshTokenUpdated` so you can persist it.

This is the same pattern that the demo app uses internally, only with its own wiring and file structure.

***

#### 6. Summary

If you build your own app but still use the VARIO App Framework backend:

1. **Create an App** in VARIO Cloud and get `appIdentifier`, `clientId`, `clientSecret`.
2. **Store one refresh token per installation** when your app is installed/authorized.
3. **Install the framework backend**:

   ```
   npm install @vario-software/vario-app-framework-backend
   ```
4. **Initialize the framework** with your app client config.
5. **Create a helper** (similar to the demo app) that:
   * loads the installation’s `refreshToken`
   * asks the framework for an API client
   * persists rotated refresh tokens (if any)
6. **Use that API client** in all your route handlers instead of talking to the VARIO Cloud API directly.

You still use OAuth2 with the **refresh-token grant type**, but the **framework** hides all low-level token handling and keeps your own code focused on business logic.


---

# 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/documentation/apps/authentication.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.