Constellation DX API OAuth Authorization setup

Pega provides many constellations DX APIs for various categories like Case Management and processing, Assignment processing and many other categories. All these APIs are predeveloped and as developer you can use them as they are without any customization.

To know the basics of OAuth, please visit - OAuth - Open Authorization basics

But in order to use them you must understand the security associated with the API.

By default, all DX APIs are secured with OAuth authorization. And to use these APIs you need to have basic understanding of OAuth and also need to perform some configuration to invoke them. In this article we will talk about how you can invoke these APIs from Pega API Help screen.

Pega API Help screen

You need to do two things to invoke API from Pega API Help Screen.

1. Create OAuth Client Registration rule.

2. Invoke DX API from Pega API Help Screen.

Create OAuth Client Registration rule

Purpose of OAuth client registration rule in Pega is to register the caller of the API in Pega. Since Pega is hosting these APIs, Pega is working here as OAuth provider and the caller of the API needs to be registered at OAuth provider in advance so that when caller send the API execution request, Pega can authorize the caller and allow the API execution.

Developer Studio -> Left Panel Records -> Security -> OAuth Client Registration ->Create

In the next screen give the Description and Name.

After this, the OAuth Client registration rule will appear, and it will show some information like Client Id, Client Secrete and many URLs. All these are generated by Pega and you cannot modify them. This rule has two key sections, first where you see client id and secrete and other with Supported grant types.

Client Id and Secrete is like Username and password. So, when API is called from Pega API Help Screen, it is considered as a separate application, and it will send client id and secrete to Pega for authorization. In this section all fields are read only.

Supported Grant type This section mainly deals with how Pega will create a requestor after successful authentication of the API. Pega uses this section to know access group to associate with API requestor which will be used to execute the logic of the API. If we don't configure this section properly then service execution will not find the rules to execute.

Note - Both of these sections have a lot of information and each field has a significance in OAuth authentication but in this blog, we will not go deep into all these.

In support Grant type select Client Credential Check box. After this check box, you can either give a specific Operator, or you can mention specific access group.

Note - When configuring authentication for a Pega service, you can reference either an Operator ID or an Access Group. Regardless of which option you choose, Pega ultimately relies on the Access Group to determine the context in which the service runs. Supplying an Operator ID does not cause the service to behave like a browser requestor session. Instead, Pega uses the operator’s primary Access Group—including its roles, application stack, and associated privileges—at the moment the service is executed.

After giving above information, don't click Save button at the top right corner of the rule. Before saving you need to click on View and Download button in Client ID and Secrete section. This will generate a text file which will have information to be used at the time of calling the API. So, save the file at some known location as you need to use this file at the time of calling the API. Finally Save the OAuth client registration rule.

Invoke DX API from Pega API Help Screen.

Whatever configuration we did above is used to tell Pega that there is an application which will call these APIs. This application will use client id and secret for authentication. Pls note here Pega API Help screen is treated as a separate application when it comes to calling DX API secured with OAuth.

To open Pega API Help Screen follow Developer Studio -> Resource Icon -> Pega API. Select Constellation DX APIs from Service Package Drop down

Click on Authorize button. The pop-up window will show different ways of authentication; we need to go where Client Credential is shown and Enter the Client Id and secrete from the file you downloaded above. Click on Authorization button. This way all the calls from this window are authenticated with this Client ID and Secret.

After successful authorization, you can try any DX API listed in the Pega API Help screen by providing property input parameters.

If you have any further question on DX API, pls drop your questions in comment box below, out team will get back to you soon.