Authentication

Obtain an access token with OAuth 2.0 — password, authorization code and device code grants.

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.

The exact URLs for the authorization and token endpoints depend on your tenant configuration. They can be found in the API-Clients section of the Admin Center. In the examples below, replace https://sso.vario.cloud/realms/<TENANT>/protocol/openid-connect/ with your actual base URL.

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.

Authentication URL vs. API base URL The URLs above belong to the identity server (sso.vario.cloud) and are used only to obtain and refresh access tokens. Your actual API requests go to your tenant-specific API base URL, https://{subdomain}.vario.cloud/api/vario. The exact base URL for your installation is also included in the tenant-specific OpenAPI specification, which you can download from your VARIO ERP in support mode. See the Introduction for details.

---

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.

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.

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/<TENANT>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "username=<user-name>" \
  -d "password=<user-password>" \
  -d "client_id=<your-client-id>" \
  -d "client_secret=<your-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)

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.

Typical flow

1. Redirect the user to the VARIO-Cloud authorization endpoint:

   curl GET https://sso.vario.cloud/realms/<TENANT>/protocol/openid-connect/auth
       ?response_type=code
       &client_id=<your-client-id>
       &redirect_uri=<your-registered-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/<TENANT>/protocol/openid-connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=<authorization-code>" \
     -d "redirect_uri=<your-registered-redirect-uri>" \
     -d "client_id=<your-client-id>" \
     -d "client_secret=<your-client-secret>"

5. The response contains an access_token (and usually a refresh_token), which you then use for API calls.