Integrate an OAuth 2.0 client

OAuth 2.0 clients are typically used for system-to-system communication on behalf of a user. In Airlock SaaS, an OAuth 2.0 client enables access to the Airlock SaaS public API in order to perform specific actions on your tenants. Currently, supported actions include uploading and activating Airlock IAM configurations for the selected tenant.

This article details how to create, edit, and delete OAuth 2.0 clients in the Airlock Console. It also shows how to authenticate with the API and perform specific actions on your tenants.

Managing OAuth 2.0 clients

Prerequisites

To create, edit, and delete OAuth 2.0 clients, you need the SaaS Administrator role. For details, see SaaS roles and permissions.

Creating an OAuth 2.0 client

1. In the Airlock Console, go to:
   Administration >> OAuth 2.0 clients

2. Click New OAuth 2.0 client to open the creation dialog.

3. Enter the following information:

   • Name: Enter a descriptive name for the OAuth client.

   • Permissions: Select the actions the OAuth client is allowed to perform. Select at least one permission.
     Note that after the OAuth client is created, you cannot change its permissions.
     Currently (May 2026), the following permissions are available:

     • Config activate (non-production tenants only): Activate a configuration.

     • Config upload: Upload a configuration.

     • Vault edit: Create, edit, and delete secrets.

     • Vault view: View secrets.
       Additional permissions may be added in future releases.

   • Tenant access: Select the tenant(s) this OAuth client can access. Select at least one tenant. You can change the tenant selection after the client is created.

4. Click Save.
   ▶ The new OAuth client's credentials — i.e., Client ID and Client secret — are shown.

5. Copy the credentials and store them securely.
   ▶ You need these credentials to access the Airlock as a Service public API.

   Notice Copy and store the client secret now. For security reasons, you cannot view it again later.

6. Click Close.

Reading and editing an OAuth 2.0 client

To view and edit the details of an existing OAuth 2.0 client, click its entry in the list shown in the OAuth 2.0 clients dialog. The next dialog displays the OAuth client's current settings, including its name, ID, granted permissions and tenant access. If needed, you can modify the client's name or adjust the tenants to access. The client secret and granted permissions, however, cannot be changed.

Deleting an OAuth 2.0 client

Currently, it is not possible to delete an OAuth 2.0 client. If you want to remove one, contact SaaS Support.

Accessing the SaaS public API with an OAuth 2.0 client

You can use the OAuth 2.0 clients to access the SaaS public API and perform granted actions on your tenants. To be able to do so, the OAuth client must authenticate to the public API using an access token, which is obtained via the OAuth Client Credentials Grant flow - a standard mechanism for machine-to-machine authentication without user involvement.

This section first explains how to obtain the access token. It then shows how to authenticate to the Saas public API and perform a granted action.

Step 1: Obtaining an access token

To obtain an access token for an OAuth 2.0 client, you must call the OAuth 2.0 token endpoint of the Loginapp REST API.

Prerequisites

You must include the OAuth 2.0 client's ID and secret in the request. These credentials are provided by the Airlock Console when you created the OAuth 2.0 client. Make sure you have them available now.

Instructions

Configure your POST request as follows:

POST https://manage.airlock.cloud/login/rest/oauth2/authorization-servers/management-center/token 
Authorization: Basic {{oauth-client-id oauth-client-secret}} 
Accept: */* 
Content-Type: application/x-www-form-urlencoded; charset=utf-8 
 
grant_type = client_credentials & 
scope = CONFIG_ACTIVATE CONFIG_UPLOAD

Path to the OAuth 2.0 token endpoint

• https://manage.airlock.cloud/login/rest/oauth2/authorization-servers/management-center/token

Request headers

• Authorization: Defines the authentication type. Here, a basic authentication (Basic) is sufficient. As username/password (oauth-client-id oauth-client-secret), enter the OAuth 2.0 client's ID and secret that you stored earlier when you created the OAuth 2.0 client.

• Accept: Defines the accepted media types in the response. Here, the response may contain any media type (*/*).

• Content-Type: Specifies the format of the request body. Must be set to URL-encoded form data with UTF-8 character encoding (application/x-www-form-urlencoded; charset=utf-8)

Request body

• grant_type: Must be client_credentials (OAuth Client Credentials Grant).

• scope: Space-separated list of permissions granted to the OAuth 2.0 client. Supported scopes:

  • CONFIG_ACTIVATE : Activate a configuration.

  • CONFIG_UPLOAD : Upload a configuration.

  • VAULT_EDIT: Create, edit, and delete secrets.

  • VAULT_VIEW: View secrets.

The above POST request returns the following response:

{ 
    "access_token": "...", 
    "scope": "CONFIG_ACTIVATE CONFIG_UPLOAD", 
    "token_type": "Bearer", 
    "expires_in": 180 
}

access_token: This token is required to authenticate the OAuth 2.0 client with the SaaS public API. Store the token value for the following step.

Step two: Accessing the SaaS public API to perform a granted action

After having obtained the access token, the OAuth 2.0 client can authenticate with the SaaS public API and perform the previously granted permissions.

Instructions

Configure your POST request as follows:

POST https://manage.airlock.cloud/api/public/v1/tenants/{tenantId}/{granted-action} 
Authorization: Bearer {{access_token}}
Accept: application/json
Content-Type: application/json
X-Same-Domain: 1

Path to the endpoint in the SaaS public API

• https://manage.airlock.cloud/api/public/v1/tenants/{tenantId}/{granted-action}

  • tenantId: A single, unique 6 characters long identifier of the tenant. To retrieve this ID, open the Airlock Console and go to Administration >> Tenants >> <entry of the respective tenant>. The tenant's ID is now displayed in the URL, e.g., https://manage.airlock.cloud/ui/administration/tenants/1t6y75, where the tenant ID is “1t6y75”.

  • granted-action: The action to perform, e.g., configs to upload a new configuration to the specified tenant, or config-activations to activate the specified configuration for the specified tenant. For up-to-date specifications, see the SaaS API reference.

Request headers

• Authorization: An OAuth 2.0 bearer token (Bearer) is used to authenticate with the SaaS API, with the access_token you previously obtained as valid token value.

• Accept / Content-Type: These headers define the accepted body formats for the response and request. They must both be set to JSON (application/json), unless specified otherwise in the SaaS API reference.

• x-xsrf-token: You must pass an X-XSRF token in the request, in order to mitigate Cross-Site Request Forgery (CSRF) attacks. This value can be hardcoded (as in the above code snippet) or obtained from any GET request and then used in all subsequent POST requests.

• Cookie: The value of the XSRF-TOKEN cookie specified here must match the value of the x-xsrf-token header above.