--- title: OAuth Consent Management Service description: PingFederate includes a REST-based web service to manage OAuth consent administratively. component: pingfederate version: 13.0 page_id: pingfederate:developers_reference_guide:pf_oauth_consent_management_service canonical_url: https://docs.pingidentity.com/pingfederate/13.0/developers_reference_guide/pf_oauth_consent_management_service.html revdate: March 6, 2024 section_ids: endpoints: Endpoints logging: Logging --- # OAuth Consent Management Service PingFederate includes a REST-based web service to manage OAuth consent administratively. The OAuth consent management service enables retrieval and revocation of consent and their associated attributes on a per-client or per-resource owner basis. Beginning with PingFederate 12.1, the `authorizationDetails` JSON field in responses from this endpoint has been deprecated and replaced with the `authorizationDetail` and `authroizationDetailDescription` fields. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Client records must be stored in an external client data store.Learn more in [OAuth client datastores](../administrators_reference_guide/pf_oauth_client_datastore.html). | Applications must authenticate to this web service using HTTP Basic authentication and credentials validated through an instance of a password credential validator (PCV) *(tooltip: \
\

Configures a centralized location for user credential validation. The validator instances can then be referenced by PingFederate.\

\
)*. The PCV instance, in turn, must be selected in the OAuth authorization server(AS) configuration. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Before using this endpoint, go to **System > OAuth Settings > Authorization Server Settings** and select the **Bypass Authorization for Previously Approved Consents** checkbox.The endpoint won't return consents unless this option is enabled. | ## Endpoints * Manage by client `/pf-ws/rest/oauth/clients//consents]` * Manage by user (based on the USER\_KEY value) `/pf-ws/rest/oauth/users//consents]` * 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. 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//consents` or `GET /oauth/users//consents` request. If this parameter isn't 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 ```json { "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 returnedReturned when revoking a consent. | | `401` | Invalid CredentialsThe user doesn't exist, the password is incorrect, or the user account is locked. | | `404` | Not FoundReturned when the requested consent or client is not found. | | `500` | Internal Server ErrorAn unknown error has occurred. | ## Logging PingFederate records the actions performed through this endpoint in the `runtime-api.log` file. While the events themselves aren't 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.