Configure OAuth 2.0 Clients for API Access

OAuth 2.0

In order to authenticate as an API client with Crosswork Assurance, users can use OAuth 2.0. In this guide, we will explain how to configure Postman to use OAuth 2.0 authentication.

Note: While this guide uses Postman, other API clients that support OAuth 2.0 with PKCE (such as Bruno) can also be configured using the same authentication parameters.

Requirements

Before proceeding, ensure you have:

• An API client that supports OAuth 2.0 with PKCE (for example, Postman or Bruno) installed on your computer
• A valid Organization Owner account for your instance of Crosswork Assurance (for example, the default admin user for the deployment).

Phase 1: Set Up Your API Client

Step 1. Create a Request

1. Enter your request URL in Postman (or Bruno).
   In this example, we will perform a call to retrieve connector configs: GET /api/v2/connector-configs.

2. Enter the tenant domain as appropriate for your Crosswork Assurance deployment.
   Note: Sending the request will result in a 401 response from Crosswork Assurance.

Step 2. Select OAuth 2.0

1. From the Authorization tab for the request, set the Type to OAuth 2.0.

Phase 2: Obtain Client ID and Project ID from Zitadel

To complete the OAuth 2.0 configuration, you need two values from your deployment's identity and access management service (Zitadel):

• Client ID — identifies the AnalyticsUI application
• Project ID — required for the authorization scopes

Note: You can obtain these values using either the Zitadel UI or the tenant info API.

Step 1. Log In to Zitadel

Important: You must use the admin user account to perform this step.

1. Log in to your deployment's identity and access management service (Zitadel) at: https://auth.{{domain-name}} if your deployment is configured with a domain name or https://{{ip}}:3443 if it is not.

2. Navigate to the tenant organization.
   Note: In this example the organization is named pca.
   

Step 2. Copy the Project ID

1. From the Projects tab, select the Analytics project.
   

2. On the Analytics project overview page, copy the Resource Id. This is the Project ID you will use in the Scope configuration.
   

Step 3. Copy the Client ID

1. Choose the AnalyticsUI User Agent Application.
   

2. From the top-right corner of the screen, copy the Client Id.
   

(Alternative) Use the Tenant Info API

You can retrieve the Client ID and Project ID programmatically without logging in to Zitadel.

Request:

GET https://{tenant}.{domain}/api/v1/onboarding/tenant-info

Example:

curl -s https://warsaw.northbound.npav.accedian.net/api/v1/onboarding/tenant-info
{
  "data": {
    "attributes": {
      "allowPasswordAuth": false,
      "providerLinks": null,
      "tenantId": "a59f2feb-41a7-4de4-ad31-8f55cd2d6674",
      "tenantName": "warsaw",
      "domain": "warsaw.northbound.npav.accedian.net",
      "zitadelAuth": true,
      "zitadelConfig": {
        "authority": "https://auth.northbound.npav.accedian.net:443",
        "clients": [
          {
            "appId": "371739744133983139",
            "clientId": "371739744134048675",
            "name": "AnalyticsAppM2M"
          },
          {
            "appId": "371739744217869219",
            "clientId": "371739744217934755",
            "name": "AnalyticsUI"
          },
          {
            "appId": "371739744301755299",
            "clientId": "371739744301820835",
            "name": "Orchestrator"
          }
        ],
        "organizationId": "371739743345453987",
        "projects": [
          {
            "name": "Analytics",
            "projectId": "371739743714552739"
          }
        ]
      }
    },
    "id": "warsaw",
    "type": "tenant-info"
  }
}

Phase 3: Complete Configuration in Your API Client

Step 1. Enter the Required OAuth 2.0 Configuration

1. Return to your API client and enter the following values for the Oauth 2.0 configuration:

Note: In this example, the domain name configured for the deployment is npi.npav.accedian.net and the tenant is pca.

Step 2. Obtain an Access Token

1. Click the Get New Access Token button.
   A window will appear asking you to log in.

2. Log in using your API user's credentials.

3. Click the Use Token button.

Step 3. Send the Request

1. Send the request. You will now be authenticated.