The OAuth consent management service enables retrieval and revocation of consent and their associated attributes on a per-client or per-resource owner basis.

Important:

Client records must be stored in an external client data store.

To learn more, see OAuth client datastores.

Applications must authenticate to this web service using HTTP Basic authentication and credentials validated through an instance of a password credential validator (PCV). The PCV instance, in turn, must be selected in the OAuth authorization server (AS) configuration.

Note:

Before using this endpoint, go to System > OAuth Settings > Authorization Server Settings and select the Bypass Authorization for Previously Approved Consents check box.

The endpoint will not return consents unless this option is enabled.

Endpoints

Manage by client
/pf-ws/rest/oauth/clients/<clientId>/consents[/<consentId>]
Manage by user (based on the USER_KEY value)
/pf-ws/rest/oauth/users/<userKey>/consents[/<consentId>]
Parameters
Parameter Description

clientId

The client ID for which to retrieve or revoke consents.

Required to manage consents for a specific client.

userKey

The USER_KEY value for which to retrieve or revoke consents.

Required to manage consents for a specific resource owner.

Tip:

The USER_KEY value varies, depending on the mapping configuration defined in the IdP Adapter Grant Mapping, Authentication Policy Contract Mapping, or Resource Owner Credentials Grant Mapping tabs.

consentId (optional)

The consentId of the consent to revoke or for which to retrieve the specific details.

The value corresponds to the value of the id field found in the JSON array of consents returned from a previous GET /oauth/clients/<clientId>/consents or GET /oauth/users/<userKey>/consents request.

Note:

If this parameter is not specified, the request applies to all consents for the client or user.
Cross Site Request Forgery Protection
Both endpoints require the X-XSRF-HEADER HTTP header with any value to prevent cross-site request forgery.
Example
Sample request
A request to retrieve all consents for a client with an ID value of ac_oic_client. 
GET /pf-ws/rest/oauth/clients/ac_oic_client/consents HTTP/1.1
Host: localhost:9031
Authorization: Basic YWRtaW46MkZlZGVyYXRl
X-XSRF-HEADER: PingFederate
Sample response
{
  "items": [
    {
      "id": "JDu17McN2ZFDANnHKtpATmrKjHISDVpW",
      "userKey": "asmith",
      "scope": "openid",
      "clientId": "ac_oic_client",
      "created": "2023-12-04T20:05:10.000Z",
      "updated": "2023-12-04T20:05:10.000Z"
    },
    {
      "id": "d1fGI9yFwRJrsxurEw0fX7WMFX22uoEW",
      "userKey": "asmith",
      "scope": "profile",
      "clientId": "ac_oic_client",
      "created": "2023-12-04T20:05:10.000Z",
      "updated": "2023-12-04T20:05:10.000Z"
    }
  ]
}
Return codes
Code Description

200

Success

204

Success with no content returned

Returned when revoking a consent.

401

Invalid Credentials

The user does not exist, the password is incorrect, or the user account is locked.

404

Not Found

Returned when the requested consent or client is not found.

500

Internal Server Error

An unknown error has occurred.

Logging

PingFederate records the actions performed through this endpoint in the runtime-api.log file. While the events themselves are not configurable, you can adjust the log4j2.xml configuration settings to alter the format and desired level of detail surrounding each event.

Each log entry contains information relating to the event, including:

  • Time the event occurred on the PingFederate server
  • Administrator username performing the action
  • Authentication method
  • Client IP
  • HTTP method
  • REST endpoint
  • HTTP status code

Each of the above fields is separated by a vertical pipe (|) for ease of parsing.