> 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/rest-api/authentication.md). # Authentication ### OAuth 2.0 authorization methods in VARIO Cloud In addition to its App frameworks, VARIO-Cloud exposes an HTTP API that is protected using **OAuth 2.0**.\ You can choose between three authorization methods: * **Password** grant * **Authorization Code** grant * **Device Code** grant All methods use the **client credentials** (`clientId`, `clientSecret`) that you obtain when creating an App in the Developer section. {% hint style="info" %} The exact URLs for the authorization and token endpoints depend on your tenant configuration.\ They can be found in the API-Clients section in the Admin Interface\ In the examples below, replace `https://sso.vario.cloud/realms//protocol/openid-connect/` with your actual base URL. {% endhint %} {% hint style="warning" %} **User-Agent required**\ All API requests must include a `User-Agent` header (e.g. `MyApp/1.0`). Requests without `User-Agent` are blocked with `403 Forbidden`. {% endhint %} *** ### Password grant The **Password grant** allows your App to exchange a user’s **username and password** directly for an access token. #### When to use * For **trusted, server-side** applications that can securely store user credentials and client secrets. * For **system integrations** where a technical user is used for automation. {% hint style="warning" %} **Security warning**\ Do **not** use the Password grant in public clients (single-page apps, mobile apps without secure storage, etc.), because it requires handling the user’s raw password. {% endhint %} #### Requirements To use the Password grant, you need: * a **user account** in the VARIO-Cloud tenant * the user’s **password** * the App’s **Client ID** (`clientId`) * the App’s **Client Secret** (`clientSecret`) * the user must be **explicitly allowed** to use the Password grant in their user settings #### Enabling the Password grant for a user The Password grant is disabled by default for all users and must be enabled per user and per installation. 1. Sign in to your VARIO-Cloud tenant as an administrator. 2. Open the **“Benutzer”** (Users) menu. 3. Select the user who should be allowed to authenticate via Password grant. 4. Select the relevant **installation** (tenant / environment) for that user. 5. Activate the checkbox\ \&#xNAN;**„OAuth-Password-Grant-Type erlauben“**\ (Allow OAuth Password Grant Type). 6. Save your changes. Only users with this option enabled can obtain tokens via the Password grant. #### Requesting a token with the Password grant Once the user is enabled, you can request an access token with a standard OAuth 2.0 Password grant request: ``` curl -X POST "https://sso.vario.cloud/realms//protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=password" \ -d "username=" \ -d "password=" \ -d "client_id=" \ -d "client_secret=" ``` The response contains an `access_token` (and usually a `refresh_token`), which you then use for API calls. *** ### Authorization Code grant The **Authorization Code grant** is the standard flow for **web applications** and other clients that can handle browser redirects.\ The user signs in via the VARIO-Cloud login page, and your App never sees the user’s password. #### When to use * For **browser-based** or **server-side web apps** with a backend that can receive HTTP callbacks. * When you want the user to explicitly **approve** the App’s access the first time it connects. #### Requirements To use the Authorization Code grant, you need: * a **user account** in the tenant (the end-user who will authorize the App) * the App’s **Client ID** and **Client Secret** * a **running OAuth callback server**, i.e. a backend endpoint that: * is reachable from the internet, and * can receive the `redirect_uri` callback * the callback URL must be **registered** for the App (according to your tenant configuration) {% hint style="danger" %} **Important**\ Unlike the Password grant, you **do not** send the user’s username/password to the token endpoint.\ The user authenticates directly against VARIO-Cloud in their browser and must **confirm** the access for your App on first connection in order to receive a valid token. {% endhint %} #### Typical flow 1. **Redirect the user** to the VARIO-Cloud authorization endpoint: ``` curl GET https://sso.vario.cloud/realms//protocol/openid-connect/auth ?response_type=code &client_id= &redirect_uri= ``` 2. The user logs in (if not already authenticated) and is asked to **grant access** to your App. 3. VARIO-Cloud redirects the user back to your `redirect_uri` with a `code` and `state` parameter. 4. Your backend exchanges the authorization code for tokens: ``` curl -X POST "https://sso.vario.cloud/realms//protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "code=" \ -d "redirect_uri=" \ -d "client_id=" \ -d "client_secret=" ``` 5. The response contains an `access_token` (and usually a `refresh_token`), which you then use for API calls. --- # 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/rest-api/authentication.md?ask=&goal= ``` `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.