Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Security Settings for DX API

Updated on August 5, 2022

Secure access to your DX API endpoints by learning about authentication settings and access role privileges.

Authentication settings for Service Package

To authenticate DX API endpoints, configure the authentication settings through the API service package.

For more information about service packages, see Service Packages.

The following types of authentication are available for a service package:

  • Basic
  • OAuth 2.0
  • Custom

For more information about the types of authentication, see Setting the context of a collection step.

Edit Service Package – Context tab

To access endpoints more securely, use OAuth 2.0 as the authentication type. For more information about OAuth 2.0 configuration, see the following articles:

Access role privileges

Every endpoint is mapped to a privilege. You can provide users with specific privileges so that they can perform the actions associated with the corresponding endpoints.

Note: The privileges are included with the PegaRULES:PegaAPI access role. By default, this role is available only to the Administrator and Author access groups. To grant a user access to the DX API, add the PegaRULES:PegaAPI access role to the user's access group.

The following table depicts the endpoints that correspond to each privilege:

HTTP methodEndpointPrivilege
POSTapi/v1/casespxCreateCase
GETapi/v1/assignments/{ID}/actions/{actionID}pxGetAssignments
PUTapi/v1/assignments/{ID}/actions/{actionID}/refresh
GETapi/v1/assignments
GETapi/v1/assignments/{id}
GETapi/v1/spaces
GETapi/v1/notifications
GETapi/v1/casetypes/{ID}pxGetCaseTypes
PUTapi/v1/casetypes/{ID}/refresh
GETapi/v1/casetypes
GETapi/v1/cases/{ID}/actions/{actionID}pxGetCases
PUTapi/v1/cases/{ID}/actions/{actionID}/refresh
GETapi/v1/cases
GETapi/v1/cases/{id}
GETapi/v1/cases/{ID}/pages/{pageID}
GETapi/v1/cases/{ID}/views/{viewID}
GETapi/v1/data/{id}pxGetDataPage
GETapi/v1/data/{id}/{metadata}
POSTapi/v1/assignments/{id}pxPerformAssignment
PUTapi/v1/casespxUpdateCase
PUTapi/v1/cases/{id}
GETapi/v1/applicationspxGetApplications
POSTapi/v1/messagespxCreatePulse
POSTapi/application/v2/messages
GETapi/v1/documents/{id}pxGetDocumentDetails
GETapi/v1/documentspxGetDocuments
GETapi/v1/messagespxGetMessages
GETapi/application/v2/messages
GETapi/v1/spaces/{id}pxGetSpaces
GETapi/v1/spaces/{id}/pins
GETapi/v1/pins
PUTapi/v1/spaces/{id}/joinpxUpdateSpace
PUTapi/v1/spaces/{id}/leave
POSTapi/v1/applicationspxCreateApplication
PATCHapi/v1/accessgroups/{ID}pxUpdateAccessGroup

Additional privileges

Additional privileges enable field-level security while performing specific actions. When field level security is enabled, user requests to Pega Platform are validated against the fields that the user added to the view. Note that read-only fields are treated as invalid. Disabled fields are treated the same as editable fields and valid if they are defined in the UI of the posted flow action. If additional fields are passed in the input, a 400 Bad Request error is returned.

Use the dynamic system setting DebugPegaAPI to log the additional fields in the Pega API Rest Service Info statements. For more information about configuring dynamic system settings, see Configuring dynamic system settings and Debugging DX API.

Note:
  • Additional privileges are not included with the PegaRULES: PegaAPI access role. To grant users, administrators, or authors access to DX API, add the additional privileges to application access roles, such as the application: PegaAPI access role.
  • Additional privileges are included with the PegaRULES:PegaAPIDX access role. To access the complete suite of security privileges for v1 DX APIs, add the PegaRULES:PegaAPIDX role in addition to the PegaRULES:PegaAPI role to your users' access groups.

The following table describes the usage of each additional privilege:

Additional privilegeUsage
pxCreateCaseDXEnables field-level security while creating a case.
Note: When the pxCreateCaseDX privilege is enabled, and the case type uses a Create stage, the pyCreatesection enables field level security. Override it in your Casetype class and add the fields you want allowed to be passed in with POST /cases.

The pyCreatesection in this situation is purely for field security checking purposes and is never shown to the user.

pxUpdateCaseDXEnables field level security while updating a case.
pxPerformAssignmentDXEnables field level security while performing assignment.
pxGetCaseDXRestricts the content of the GET /cases/{ID} endpoint to the fields contained in the review harness.
pxGetDataDXProvides access to only those data pages in built-in applications that are marked as API.
pyExcludeSummaryDataPrevents the API from sending the SummaryData metadata in the response to avoid exposing sensitive data.

Application settings

The pyDXAPIEncodeValues application setting protects users from cross-site scripting attacks, and applies to the following endpoints:
  • GET /casetypes/{ID}
  • GET /casetypes/{ID}/refresh
  • GET /assignments/{ID}/actions/{ID}
  • GET /assignments/{ID}/actions/{ID}/refresh
  • GET /cases/{ID}/actions/{ID}
  • GET /cases/{ID}/actions/{ID}/refresh

If the pyDXAPIEncodeValues application setting is set to true, all the special characters in the response are converted into HTML entities. For example, 100% is converted to 100%.

Tags

Pega Platform 8.7 DX API

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us