Create OAuth 2.0 access token to call Pega API

[Will_Cho]

This knowledge sharing article shows an implementation pattern of calling a Pega API, which requires an OAuth 2.0 authentication. It shows how to generate an OAuth 2.0 access token and how to call a Pega API using the access token to auto create cases in Pega application.

Client use case

This is a technical user story. Client wants to unit test a Pega API (POST/cases) to create a new case in Pega application. Client requires to use OAuth 2.0 authentication method when invoking the API. In practice, an external system will invoke the Pega API to automatically create cases.

Configurations

The configurations are organized into three parts:

1. Configure an OAuth 2.0 Client Registration instance in Pega.
2. Generate an OAuth 2.0 access token (using Postman)
3. Call Pega API - POST/cases (using Postman)

(Part A - Configure an OAuth 2.0 Client Registration instance in Pega)

Step 1 - Create a new OAuth 2.0 Client Registration instance in DEV Studio.

In this example, we specified an Operator ID in the client credentials section. This Operator ID is mapped to an access group that has access to the case type.

Click to regenerate the client secret and download the client credentials file.

Step 2 - Save the instance.

(Part B - Generate an OAuth 2.0 access token (using Postman))

Step 1 - Copy the Access token endpoint value from the client credentials file generated above.

Step 2 - Configure a Postman request to invoke the access token endpoint.

Set the URL and the key-value pair under Headers.

Set the key-value pairs under Body.

• client_id and client_secret can be copied from the client credential file.

Step 3 - Click Send to generate an access token.

(Note: if you received an “Cloud Agent Error: Couldn’t resolve host.” error, switch from Cloud Agent to Desktop Agent in Postman. The Desktop Agent runs locally on your machine and can access internal networks. Go to the bottom-right of Postman where it shows the agent selector and choose “Desktop Agent”)

Go to jwt.io and copy & paste the access token string to decode. As we can see, the decoded information shows the same Operator ID ([email protected]) that we specified in the OAuth 2.0 client registration above.

(Part C - Call Pega API - POST/cases (using Postman))

Step 1 - Configure the Authorization settings**.**

• Select POST and enter the URL for Pega API (cases)
• Click the Authorization tab.
• Select ‘OAuth 2.0’ in the Auth Type dropdown.
• Copy and paste the access token as shown below**.**

Step 2 - Specify the Request data and click Send to get a successful response

Step 3 - Verify that the APP-2005 case is created successfully in Pega.

Additional information

• Note that the api service is set to require OAuth 2.0 authentication.

​

Please feel free to leave any comment or question.

Constellation 101 Series

Enjoyed this article? See more similar articles in Constellation 101 series.

[Michel_Kraaij (Michel Kraaij - van den Berg)]

@Will Cho Thanks for this insight!

Just FYI, if anyone is interested in more in depth knowledge on how to use the Pega Constellation DX APIs (and, for example, how to utilize the APIs for software testing), reach out to the Pega Academy. They have a dedicated course on this topic.

(Or reach out to me. I’m one of the trainers )

[Kamil_Janeczek]

@Will ChoThanks for sharing. For those that want to check how we can authenticated from JavaScript using Oauth2, here is example: c11n-testing/lib/utils.ts at main · kamiljaneczek/c11n-testing · GitHub

[Franz_H (Franz Hefele)]

@Will ChoMany thanks for this article!

In my opinion, a deeper dive into the different grant types could be a great addition for a version 2.

[Will_Cho]

@DaniV17021618 Do you have a local login URL that doesn’t go through SSO? I would try that if available. I haven’t encountered 401 error when i did the demo above. If nothing works, i’d suggest to raise a Pega incident ticket.

[JBRaghuraamm (Raghuram Jonnadabattaru)]

@Will Cho how to use the dx api of an application from another pega constellation application , A and B are two pega parallel constellation applications , say if A wants to use B’ resources like getting data or like in your example to create a case. assume A and B are in same pega environment.

[Denny_Varghese]

@Will Cho For DX API v2 too, same OAuth implementation you tried ?

[Denny_Varghese]

@Will Cho Thanks..

Also can you please share some insight on how to use authorization code instead of token credentials in DX API OAuth ? I’m looking for some details which i can try implment in community edition ?

[DaniV17021618 (Dani Vi)]

@Will Cho

Hi Will, I have followed your tutorial but I get a 401 Unauthorized error when I try to generate a token in Step 3. I have tried my operator id and different access groups I am part of but still get a 401 error. My team’s application uses SSO and I think this may be causing the issue. Do you have any advice/tips on how to handle this kind of issue? Thank you

Access token endpoint: https://sso{server}/prweb/PRRestService/oauth2/v1/token

[JBRaghuraamm (Raghuram Jonnadabattaru)]

@Franz Hyes, I do agree with you, a detailed article on grant types is much helpful

[Will_Cho]

@Denny Varghese DX API v2 should also support OAuth2.0

[Denny_Varghese]

@Will Cho Thanks for guiding. I have created the question below. Please respond if you have any inputs.

DX API OAuth 2.0 Authorization Code Implementation | Support Center

[Anoop_Krishna]

@Kamil Janeczek The URL you have provided is not working. Can you please provide the latest working URL

[Will_Cho]

@JBRaghuraamm There is a rich set of Pega APIs you can use.. including to get data from another Pega application. I normally first try that in Pega API landing page or using other API client tool like Postman/Bruno to test and learn how to use each API.

[Will_Cho]

@Denny Varghese Thanks for your inquiry. This article posting is more focusing on OAuth 2.0 access token. Would you be able to create a separate Question posting with the question and more details about the authorization code? If I have any relevant knowldege, i’ll also provide my inputs or others should be able to help, too.

[Denny_Varghese]

@Will Cho Hello ,

Could you please help on the latest question I asked ?

[Will_Cho]

@Denny Varghese Sorry, i may have missed your inquiry. I haven’t used the authorization code, but I did some Copilot search on internal Pega documents. Please validate before use.

“If you’re building a Connect REST rule (server‑to‑server, no user), don’t use Authorization Code—use a confidential client flow like Client Credentials or JWT Bearer instead. Those are intended for headless connectors and service accounts. Authorization Code is overkill there and requires an interactive user redirect”

[MadhuSudan_Kaka (MadhuSudanRao Yadav Kaka)]

Hi Will do,

Thanks for the detailed setup, I am trying to generate for Pega Access Token for new users whose Operator IDs do not yet exist in Pega. The user identity comes from JWT (sid).

Current Configuration

Client Registration (JWT Bearer)

• JWT validation works (signature + standard claims OK).

Token Profile

Claims validation

• iss → Constant (IdP identifier)

• aud → Constant (token endpoint)

• sub → Incoming claim; Compare = blank (we do not validate sub value)

Claims mapping

• sid → pySubject (and optionally also pxRequestor.pyUserIdentifier for logging)

• exp → (epoch seconds mapped appropriately)

Identity Mapping → Post‑processing activity (Applies‑To: Data-Admin-Operator-ID)

• Reads the user ID from claims (.pySubject or .pxRequestor.pyUserIdentifier)

• If operator does not exist:

  Opens a model operator (e.g., TempOperator@ABC)

  Clones into a new page and sets:

  .pyUserIdentifier =

  .pyAccessGroup, .pyOrganization, .pyDivision, .pyUnit, .pyWorkGroup, .pyEnable = true

  Obj-Save (WriteNow = true)

  Re‑opens the new operator by key to confirm it exists

  Sets .pySubject = on Primary (not on any temp page)

Even after creating the operator and setting pySubject on Primary, we are getting:

ERROR … IdentityMapper: Unable to retrieve Operator Page ERROR … JWTIdentityMapper: No operator is associated with the token com.pega.pegarules.integration.engine.internal.services.IdentityMapperException: No operator is associated with the token

Appreciate any pointers, examples, or confirmation of the recommended pattern in 25.1.1. Happy to share a sanitized ruleset snippet if needed.

[Will_Cho]

Thanks for the question. I haven’t worked on the scenario where Operator ID does not exist and may not have a definitive answer.

One thing I can think of is.. maybe try the access group option in the Client credentials (instead of OperatorID) and see what happens.

Besides, I asked Copilot to search internal documents and provide inputs. Please find the attachment and see if you get any useful pointer.

Copilot response.docx (19.2 KB)

[MadhuSudan_Kaka (MadhuSudanRao Yadav Kaka)]

Hi Will,

Thank you for taking the time to look into this and share the insights, really appreciate it.
On the Access Group in Client Credentials suggestion: in our case, user entitlements vary by user, so a single static AG wouldn’t produce tokens with the correct fine‑grained access. We need the token to reflect per-user entitlements, which for us means resolving to (or deriving from) a specific Operator ID rather than a shared AG.

Questions for anyone who has solved this in Infinity:

Is there a supported pattern to issue JWT Bearer tokens when the Operator doesn’t yet exist—without using a single static AG?

If someone has a working configuration where Identity Mapping creates an operator and the token is still issued in the same call, what was the minimal set of pages/parameters you populated to satisfy the identity mapper (e.g., did you map the identifier to .pyUserIdentifier on the Operator page and return that page as the mapper expects)?

Thanks again for the pointers—super helpful to narrow the viable patterns.