PingOne Platform APIs

User OAuth Scope Consents

A user OAuth scope consent resource is a record of a user’s OpenID Connect OAuth scope consents. The OAuth scope consent service gives end users the ability to control the user data they wish to share with third party applications. These consents granted through PingOne help enterprises build trust with customers who want to use third-party applications with the enterprise’s service but want control over the data they are agreeing to share.

This service provides operations to create, read, and update user OAuth scope consent resources. This service applies only to applications that have their protocol property set to OPENID_CONNECT.

Applications with a protocol value of OPENID_CONNECT always include the openid scope as part of the application’s resource grant. However, to grant any other OpenID Connect scopes to the application, such as the profile scope, you must specify the resource grant specifically using the Create Grant endpoint.

You need the Identity Data Admin role to perform operations on user oauth scope consent resources.

Expanding and filtering response data

You can expand GET {{apiPath}}/v1/environments/{{envID}}/users{{userID}}/oauthConsents and GET {{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/oauthConsents/{{oauthConsentID}} results with the expand=applications query parameter to return additional information about the associated application in the response.

You can filter a user’s consents by application ID or by application name using the query parameters filter=application.id eq "{{appID}}" or filter=application.name eq "{{appName}}" on GET operations.

Property Type Required Mutable Description

application

Relationship

Optional

Mutable

A relationship that specifies the application associated with this OAuth scope consent.

application.id

String

Optional

Mutable

A string that specifies the ID of the application associated with this OAuth scope consent. This property is required for applications with an application.appType property of PINGONE.

application.name

String

Optional

Mutable

A string that specifies the name of the application associated with this OAuth scope consent. This property is required for applications with an application.appType property of EXTERNAL.

application.appType

String

Optional

Mutable

A string that specifies the application type associated with this OAuth scope consent. Options are PINGONE and EXTERNAL.

browser

UserAgentInfo

Optional

Read only

Information that specifies the browser used to make the consent. The UserAgentInfo object includes data for name (required) and version.

consentedAt

Date

Optional

Read only

The time when a user consent occurs.

device

UserAgentInfo

Optional

Read only

Information that specifies the device used to make the consent. The UserAgentInfo object includes data for the device type.

environment.id

String

Optional

Read only

A string that specifies the ID of the environment associated with this OAuth scope consent.

operatingSystem

UserAgentInfo

Optional

Read only

Information that specifies the operating system of the device used to make the consent. The UserAgentInfo object includes data for name (required) and version.

scope

Set

Optional

Mutable

A set of strings that specifies the scopes associated with this OAuth scope consent.

status

String

Required

Mutable

A string that specifies whether the consent is valid or not. Options are ACCEPTED, REVOKED, and DECLINED.

user

Relationship

Optional

Mutable

A relationship that specifies the user associated with this OAuth scope consent.

user.id

String

Optional

Mutable

A string that specifies the ID of the user associated with this OAuth scope consent.

updatedAt

Date

Optional

Read only

The time when a user consent is updated.

Response codes

Code Message

200

Successful operation.

201

Created.

400

The request could not be completed.

401

You do not have access to this resource.

404

The requested resource was not found.

In addition to the general error codes, user OAuth scope consent operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [<field> <message>]

When and details

When: A POST /users/{ID}/oauthConsents request body omits application or scope, or a PATCH revoke request body omits status

Details: must not be null for an omitted application or status, or must not be empty for an omitted scope, for example Validation Error : [application must not be null].

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request. for the application and scope checks, or Validation Error : [scope Must not contain whitespace] for a scope containing whitespace

When and details

When: A POST /users/{ID}/oauthConsents request references an application that is not an OpenID Connect application, supplies a scope containing whitespace, or supplies scopes that are not defined for the environment or not granted to the application

Details: applicationId is not OIDC application with target application.id; scopes for oauth consent are invalid with target scope for undefined or ungranted scopes; or Must not contain whitespace with target scope for a scope containing whitespace

400

INVALID_DATA

REQUIRED_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /users/{ID}/oauthConsents request supplies no application ID and no application name

Details: application id or name is required, with target application

400

INVALID_DATA

INVALID_VALUE

Message: must be one of [ACCEPTED, DECLINED] or must be one of [REVOKED]

When and details

When: A create request sets status to a value other than ACCEPTED or DECLINED, or a revoke request sets status to a value other than REVOKED

Details: None.

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /users/{ID}/oauthConsents request matches more than one existing consent by application name

Details: Application name matches more than one existing consent.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: The directory service cannot validate the user for the operation

Details: Failed to validate the user. or User doesn’t exist.

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The user’s population cannot be resolved when authorizing the operation

Details: You do not have permissions to access this resource.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the agreements:read:oauthConsent permission (GET operations), the agreements:create:oauthConsent permission (POST operations), or the agreements:update:oauthConsent permission (PATCH operations)

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: The consent ID in the request URL does not exist for the user

Details: None.