PingFederate includes a REST-based web service for OAuth client management. This service is provided primarily for organizations with many OAuth clients, allowing programmatic management of OAuth clients, as an alternative to using the administrative console, the administrative API, or dynamic client registration.

The /pf-ws/rest/oauth/clients and /pf-ws/rest/oauth/clients/<clientId> REST resources are URL path extensions of the PingFederate runtime endpoint; for example:

  • https://www.example.com:9031/pf-ws/rest/oauth/clients
  • https://www.example.com:9031/pf-ws/rest/oauth/clients/<clientId>
Important:

The OAuth Client Management Service requires client records to be stored on an external storage.

Note:

Applications must authenticate to this web service using HTTP Basic authentication and credentials validated through an instance of a Password Credential Validator. The Password Credential Validator instance, in turn, must be selected in the OAuth AS configuration.

Tip:

The administrative API can also be used to manage OAuth clients programmatically regardless of whether the client records are managed in XML files or in a database.

Endpoint: /pf-ws/rest/oauth/clients

This resource accepts the POST, PUT, and GET methods. The POST and PUT methods described in this section require parameter name/value pairs formatted in JavaScript Object Notation (JSON).

POST
Use the POST method to creates a new client based on the parameters provided in the request. Parameters correspond to the fields on the Client Management screen. The required MIME type is application/json.
JSON Parameters
Parameter Description
clientId

(Required)

 A unique identifier the client provides to the resource server (RS) to identify itself. This identifier is included with every request the client makes.
enabled Specifies whether the client is enabled. The default value is true. A valid value is either true or false.
name

(Required)

 A descriptive name for the client instance. This name appears when the user is prompted for authorization.
description A description of what the client application does. This description appears when the user is prompted for authorization.
clientAuthnType The authentication method that the client uses.
  • Set to none if your use case does not require client authentication.
    Note: A value other than none is required for any of the following use cases:
    • This client uses the client_credentials grant type (see the grantTypes parameter).
    • This client signs its ID tokens using an HMAC signing algorithm (see the idTokenSigningAlgorithm parameter).
    • This client is allowed to access the Session Revocation API endpoint (see the grantAccessSessionRevocationApi parameter).
    • This client sends a secret parameter value.
  • Set to SECRET for HTTP Basic authentication.

    This authentication method requires the secret parameter.

  • Set to CLIENT_CERT for mutual SSL/TLS authentication; recommended for client applications where security policies prohibit storing passwords.

    This authentication method requires the clientCertIssuerDn and clientCertSubjectDn parameters.

    Important:

    If you choose mutual SSL/TLS authentication, you must configure a secondary PingFederate HTTPS port (see the property pf.secondary.https.port in the table under Configuring PingFederate properties).

  • Set to PRIVATE_KEY_JWT check box if the client authenticates via the private_key_jwt client authentication method, as defined in Client Authentication in the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication).
secret The client password or phrase.

Required when the clientAuthnType parameter is set to SECRET.
clientCertIssuerDn The issuer DN of the client certificate.

Note that these are CA certificates imported into PingFederate on the Security > Trusted CAs screen. Alternatively, it may be set to Trust Any to trust all the issuers found on the Trusted CAs screen.

Required when the clientAuthnType parameter is set to CLIENT_CERT.
clientCertSubjectDn The subject DN of the client certificate.

Required when the clientAuthnType parameter is set to CLIENT_CERT.
tokenEndpointAuthSigningAlgorithm The signing algorithm that the client must use to sign the JWTs for client authentication.

Applicable only when the clientAuthnType parameter is provided with a value of PRIVATE_KEY_JWT.

Allowed values:
  • RS256 - RSA using SHA-256
  • RS384 - RSA using SHA-384
  • RS512 - RSA using SHA-512
  • ES256 - ECDSA using P256 Curve and SHA-256
  • ES384 - ECDSA using P384 Curve and SHA-384
  • ES512 - ECDSA using P521 Curve and SHA-512
  • PS256 - RSASSA-PSS using SHA-256
  • PS384 - RSASSA-PSS using SHA-384
  • PS512 - RSASSA-PSS using SHA-512
    Note:

    RSASSA-PSS signing algorithms require either a Java 11 runtime environment or an integration with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)

If this parameter is not provided, the client can use any of the supported signing algorithms.

enforceReplayPrevention Determines whether PingFederate mandates a unique signed JWT from the client for each request when the client is configured to authenticate via the private_key_jwt client authentication method, to transmit request parameters using in signed request objects, or to do both.

A valid value is either true or false.

Note:

The underlying Assertion Replay Prevention Service is cluster-aware (see Assertion Replay Prevention Service).
requireSignedRequests Indicates whether the client must transmit request parameters in a single, self-contained parameter. The parameter name is request. The value of the request parameter is a signed JWT whose claims represent the request parameters of the authorization request. The OpenID Connect specification calls this JWT a request object.

A valid value is either true or false.

Note:

If a client includes in an authorization request a request parameter (other than client_id and response_type) as a parameter outside of the signed request object and a claim inside of the signed request object, PingFederate always uses the claim value found inside the signed request object to process the request further.

For the client_id and response_type request parameters, the values outside of the signed request object must match the claim values inside of the signed request object. If the values do not match, PingFederate returns an error message to the client.

It is also worth noting that if a request parameter is found only outside of the signed request object, such request parameter is dropped and ignored; no error message is returned.

Tip:

Per OAuth and OpenID Connect specifications, a client must always include in an authorization request the client_id, response_type, and scope request parameters outside of the signed request object.

For more information about request object, please refer to the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#RequestObject).

If this parameter is not provided, a value of false is assumed.
requestObjectSigningAlgorithm The signing algorithm that the client must use to sign its request objects for transmission of request parameters.

Applicable only when the client may send its authorization requests using request objects.

Allowed values:
  • RS256 - RSA using SHA-256
  • RS384 - RSA using SHA-384
  • RS512 - RSA using SHA-512
  • ES256 - ECDSA using P256 Curve and SHA-256
  • ES384 - ECDSA using P384 Curve and SHA-384
  • ES512 - ECDSA using P521 Curve and SHA-512
  • PS256 - RSASSA-PSS using SHA-256
  • PS384 - RSASSA-PSS using SHA-384
  • PS512 - RSASSA-PSS using SHA-512
    Note:

    RSASSA-PSS signing algorithms require either a Java 11 runtime environment or an integration with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)

If this parameter is not provided, the client can use any of the supported signing algorithms.

jwksUrl, or

jwks

 The URL of the JSON Web Key Set (JWKS) or the actual JWKS from the client.

Only one of them is required if the client is configured to use the private_key_jwt client authentication method, to transmit request parameters in signed request objects, or to transmit CIBA request parameter in signed request objects (or to do any of them) so that PingFederate can verify the authenticity of the JWTs.

In addition, either may also be defined even if the client is not configured to use JWTs for authentication or transmission of request parameters. This flexibility allows the client to transmit request parameters in signed request objects for some requests and without the use of signed request objects for some other transactions. (For runtime processing, see Authorization endpoint.)

If the client signs its JWTs using an RSASSA-PSS signing algorithm, PingFederate must be deployed to run in a Java 11 runtime environment or integrated with a hardware security module (HSM) to process the digital signatures. (For more information on HSM integration, see Supported hardware security modules.)

Finally, if the client is configured to encrypt ID tokens using an asymmetric encryption algorithm (see the ID Token Key Management Encryption Algorithm setting), either the JWKS URL or the actual JWKS must be provided.

redirectUris URIs to which the OAuth AS may redirect the resource owner's user agent after authorization is obtained. At least one redirection URI is required by the authorization code and implicit grant types.
logoUrl The location of the logo used on user-facing OAuth grant authorization and revocation pages. (For best results with the installed HTML templates, the recommended size is 72 x 72 pixels.)
bypassApprovalPage If set to true, resource-owner approval for client access is assumed; PingFederate no longer presents to the user an authorization consent page or redirects to a trusted web application that is responsible to prompt the user for authorization for this client.

A valid value is either true or false.

If this parameter is not provided, a value of false is assumed.
restrictScopes This setting controls whether all existing common scopes and scope groups (and those created in the future) or only the select few should be made available to the client.

A valid value is either true or false.

When set to true, PingFederate limits the client to a list of common scopes and scope groups as specified by the restrictedScopes parameter.

When set to false, all existing common scopes and scope groups and those created in the future are available to the client.

If this parameter is not provided, a value of false is assumed.

Note: Depending on the configured dynamic scope patterns and whether they are defined as common or exclusive dynamic scopes, this setting and the restrictedScopes parameter value can impact the results of scope evaluation. The default scope, however, is always allowed for and available to all clients. For detailed information, refer to the Dynamic scope evaluation and per-client scope management section in Scopes and scope management.
restrictedScopes Used in conjunction with the restrictScopes parameter value of true to limit this client to a list of common scopes or scope groups in addition to the default scope. The rest and any common scopes and scope groups created in the future become invalid for the client; that is, if the client tries to use such scope or scope group, it will receive an invalid_scope error message from PingFederate.
exclusiveScopes This setting controls whether any exclusive scopes and scope groups should be made available to the client.

As needed, provide this parameter with a list of exclusive scopes or scope groups that are intended for the client. The rest and any exclusive scopes and scope groups created in the future become invalid for the client; that is, if the client tries to use such scope or scope group, it will receive an invalid_scope error message from PingFederate.

If this parameter is not provided, no exclusive scopes or scope groups are available to the client.

Note: Depending on the configured dynamic scope patterns and whether they are defined as common or exclusive dynamic scopes, this setting can impact the results of scope evaluation. The default scope, however, is always allowed for and available to all clients. For detailed information, refer to the Dynamic scope evaluation and per-client scope management section in Scopes and scope management.
grantTypes An array of one or more grant types, for which a client can request.
Allowed values:
  • authorization_code
  • implicit
  • refresh_token
  • client_credentials
  • urn:ietf:params:oauth:grant-type:device_code
  • urn:openid:params:grant-type:ciba
  • password
  • extension (JWT Bearer Token or SAML 2.0 Bearer Assertion)

(For more information about each grant type, see Grant types.)
restrictedResponseTypes An array of one or more response types, for which a client can request. .
Allowed values:
  • code
  • code id_token
  • code id_token token
  • code token
  • id_token
  • id_token token
  • token

For more information about these response types, see Definitions of Multiple-Valued Response Type Combinations (openid.net/specs/oauth-v2-multiple-response-types-1_0.html#Combinations).

If one or more response types are specified, the resulting client is only allowed to send one of the specified response types at runtime. Requests from this client with other response types will be rejected.

Additionally, it is worth noting that the response types and grant types parameters must be provided in tandem because certain response types require one or more grant types, and vice versa. The following table provides a summary of their relationship.

response type grant types
code authorization_code
code id_token authorization_code and implicit
code id_token token authorization_code and implicit
code token authorization_code and implicit
id_token implicit
id_token token implicit
token implicit
defaultAccessTokenManagerId The default Access Token Management (ATM) instance for this client.
validateUsingAllEligibleAtms Applicable only to RS clients.

If selected, this RS client is not required to specify additional parameters (access_token_manager_id or aud) to disambiguate the ATM instance in its token validation requests. When the RS client does not specify the desired ATM instance, PingFederate validates the access tokens against all eligible ATM instances. This simplifies interactions with PingAccess® by avoiding the need to align resource URIs between PingAccess and PingFederate.

This check box is not selected by default.
requireProofKeyForCodeExchange Applicable when the client is configured to support the authorization_code grant type.

A valid value is either true or false.

This field determines whether the client must provide certain parameters to reduce the risk of authorization code interception attack. For more information, see the Proof Key for Code Exchange (PKCE) by OAuth Public Clients specification (tools.ietf.org/html/rfc7636).

When enabled, this client must include a one-time string value through the use of the code_challenge parameter in its authorization request (see Authorization endpoint). It must also submit the corresponding code verifier via the code_verifier parameter in its token request when exchanging an authorization code for an access token (see OAuth grant type parameters).

If this parameter is not provided, the assumed value is false.

persistentGrantExpirationType Overrides the Persistent Grant Max Lifetime field value set globally in the OAuth Server > Authorization Server Settings screen.
Note:

This setting can be overridden per grant-mapping configuration through the use of an extended persistent grant attribute PERSISTENT_GRANT_LIFETIME. The PERSISTENT_GRANT_LIFETIME attribute is defined on the OAuth Server > Authorization Server Settings screen. Once added, the lifetime of persistent grants can be set based on the outcome of attribute mapping expressions in individual grant-mapping configurations. For grant-mapping configurations that do not require this fine-grain control, they can be configured to use the default value.
persistentGrantExpirationTime An integer representing units of time for storage of persistent grants for this client.

Required when the persistentGrantExpirationType parameter is provided with a value of OVERRIDE_SERVER_DEFAULT.

persistentGrantExpirationTimeUnit Units for the expiration time set by the persistentGrantExpirationTime parameter.
Allowed values:
  • h (hours)
  • d (days)
  • n (minutes)

Required when the persistentGrantExpirationType parameter is provided with a value of OVERRIDE_SERVER_DEFAULT.
persistentGrantIdleTimeoutType Overrides the Persistent Grant Idle Timeout field value set globally in the OAuth Server > Authorization Server Settings screen.
Allowed values:
  • SERVER_DEFAULT (the default): Use the global setting.
  • NONE: Grants do not expire due to inactivity.
  • OVERRIDE_SERVER_DEFAULT: Use in conjunction with the persistentGrantIdleTimeout and persistentGrantIdleTimeoutUnit parameters to set the idle timeout window.

If an idle timeout value is configured, the idle timeout window slides when a persistent grant is updated (see Persistent versus transient grants).

When an idle timeout value is configured without a maximum lifetime, persistent grants remain valid until they expire due to inactivity, or are revoked or removed. When an idle timeout value is configured with a maximum lifetime, persistent grants remain valid until they expire (due to inactivity or lifetime expiration) or are removed from the grant storage.

persistentGrantIdleTimeout An integer representing the inactivity timeout value for this client.

Required when the persistentGrantIdleTimeoutType parameter is provided with a value of OVERRIDE_SERVER_DEFAULT.

persistentGrantIdleTimeoutTimeUnit Units for the inactivity timeout value set by the persistentGrantIdleTimeout parameter.
Allowed values:
  • h (hours)
  • d (days)
  • n (minutes)

Required when the persistentGrantIdleTimeoutType parameter is provided with a value of OVERRIDE_SERVER_DEFAULT.
refreshRolling Overrides the Roll Refresh Token Values setting configured globally in the OAuth Server > Authorization Server Settings screen.

A valid value is either true or false.

Note that a value of true does not override the Minimum Interval to Roll Refresh Tokens (Hours) value set on the Authorization Server Settings screen.

If this parameter is not provided, the Roll Refresh Token Values setting configured globally setting in the OAuth Server > Authorization Server Settings screen is used.

OpenID Connect client settings

Note: The following parameters are only applicable when the OpenID Connect protocol is enabled in System > Protocol Settings > Roles & Protocols screen and this client supports the OpenID Connect use cases.
idTokenSigningAlgorithm The JSON Web Signature (JWS) algorithm required for the OpenID Connect ID tokens.
Allowed values:
  • none - No signing algorithm
  • HS256 - HMAC using SHA-256
  • HS384 - HMAC using SHA-384
  • HS512 - HMAC using SHA-512
  • ES256 - ECDSA using P256 Curve and SHA-256
  • ES384 - ECDSA using P384 Curve and SHA-384
  • ES512 - ECDSA using P521 Curve and SHA-512
  • RS256 - RSA using SHA-256
  • RS384 - RSA using SHA-384
  • RS512 - RSA using SHA-512
  • PS256 - RSASSA-PSS using SHA-256
  • PS384 - RSASSA-PSS using SHA-384
  • PS512 - RSASSA-PSS using SHA-512
    Note:

    RSASSA-PSS signing algorithms require either a Java 11 runtime environment or an integration with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)

Important:

If static keys for OAuth and OpenID Connect are enabled, use either an RSA algorithm or an EC algorithm that has been configured with an active static key.
idTokenEncryptionAlgorithm The algorithm used to encrypt or otherwise determine the value of the content encryption key.
Allowed values:
  • dir - Direct Encryption with symmetric key
  • A128KW - AES-128 Key Wrap
  • A192KW - AES-192 Key Wrap
  • A256KW - AES-256 Key Wrap
  • A128GCMKW - AES-GCM-128 key encryption
  • A192GCMKW - AES-GCM-192 key encryption
  • A256GCMKW - AES-GCM-256 key encryption
  • ECDH-ES - ECDH-ES
  • ECDH-ES+A128KW - ECDH-ES with AES-128 Key Wrap
  • ECDH-ES+A192KW - ECDH-ES with AES-192 Key Wrap
  • ECDH-ES+A256KW - ECDH-ES with AES-256 Key Wrap
  • RSA-OAEP - RSAES-OAEP
idTokenContentEncryptionAlgorithm The content encryption algorithm used to perform authenticated encryption on the plain text payload of the token.

Required if an algorithm is provided through the idTokenEncryptionAlgorithm parameter.

Allowed values:
  • A128CBC-HS256 - Composite AES-CBC-128 HMAC-SHA-256
  • A192CBC-HS384 - Composite AES-CBC-192 HMAC-SHA-384
  • A256CBC-HS512 - Composite AES-CBC-256 HMAC-SHA-512
  • AES-GCM-128 - A128GCM
  • AES-GCM-192 - A192GCM
  • AES-GCM-256 - A256GCM
policyGroupId The desired Open ID Connect policy.
grantAccessSessionRevocationApi Set to true to allow this client to access the Session Revocation API for back-channel session query and revocation.

A valid value is either true or false.

If this parameter is not provided, a value of false is assumed.

Note:

Generally speaking, if clients are allowed to add sessions to the revocation list, consider enabling the Check session revocation status option in the applicable Access Token Management instances so that the token validation process takes into account whether a session has been added to the revocation list. (For more information, see Managing session validation settings.)
pairwiseUserType Set to true to allow this client to use pairwise pseudonymous IDs. This parameter is set to false by default.
sectorIdentifierUri Specify one HTTPS URL only. This parameter is applicable only if pairwiseUserType is set to true.
Note: If the Track User Sessions for Logout check box is selected in the OAuth Server > Authorization Server Settings screen, you can provide two additional parameters to enable asynchronous front-channel logout for this client.
pingAccessLogoutCapable If set to true, PingFederate sends (via the browser) logout requests to an OpenID Connect endpoint in PingAccess as part of the logout process.

A valid value is either true or false.

If this parameter is not provided, a value of false is assumed.

logoutUris A list of additional endpoints at the relying parties as needed. PingFederate sends (via the browser) requests to these URIs as part of the logout process. Note that the relying parties must return an image in their logout responses; otherwise, PingFederate returns an error message or redirect to the InErrorResource parameter value (if specified)..

Device Authorization Grant client settings

deviceFlowSettingType This field controls whether to use global device authorization grant settings defined on the OAuth Server > Authorization Server Settings screen.

Allowed values are SERVER_DEFAULT and OVERRIDE_SERVER_DEFAULT.

Set to OVERRIDE_SERVER_DEFAULT and configure any of the following settings.

userAuthzUrlOverride
This field controls whether PingFederate should use a different URL, perhaps for ease of use or branding purposes, when formulating the verification URLs to be included in its device authorization responses (see Device authorization endpoint).
For example, if this field is configured with a value of https://www.example.org/welcome, PingFederate returns https://www.example.org/welcome and https://www.example.org/welcome?user_code=<activationcode> as the verification URIs.
After processing the device authorization response, which includes the verification URIs, the device presents one of them to the user. The user is expected to browse to the presented verification URI on a second device.
Important:

The target web server must redirect the browser to PingFederate at its user authorization endpoint (see User authorization endpoint). Moreover, it must also preserve the user_code parameter value (if provided).

For instance, if the base URL of your PingFederate server is https://www.example.com and this field is configured with a value of https://www.example.org/welcome, the target web server must redirect as follows:

  • https://www.example.org/welcome to https://www.example.com/as/user_authz.oauth2
  • https://www.example.org/welcome?user_code=<activationcode> to https://www.example.com/as/user_authz.oauth2?user_code=<activationcode>
pendingAuthzTimeoutOverride
The lifetime of an activation code (the user_code parameter value) in seconds.
devicePollingIntervalOverride
The amount of time in seconds that the device waits between polling requests to the PingFederate token endpoint.
bypassActivationCodeConfirmationOverride
When PingFederate receives a verification request that includes an activation code (the user_code parameter value), it prompts the user to confirm the activation code.

This field controls whether PingFederate should skip this confirmation step.

Set to true if you want PingFederate to skip the confirmation step.

Client-initiated backchannel authentication (CIBA) client settings

cibaTokenDeliveryMode The token delivery method supported by the client. PingFederate supports poll and ping.

Set to poll if the client can check for the authorization results periodically at the token endpoint.

Set to ping if the client prefers to wait for a ping callback message from PingFederate as a signal that the authorization result is ready for pickup.

If the CIBA grant type is enabled, this parameter is required; no value is assumed.

cibaNotificationEndpoint The client's notification endpoint, to which PingFederate sends its ping call back messages.

Required only if ping is the configured token delivery method.

cibaPollingInterval The number of seconds that the client must wait between its attempts to check for the authorization results at the token endpoint. When PingFederate receives a token request within this time interval, it returns a slow_down error message to the client.

A valid value ranges from 1 to 3600.

If the CIBA grant type is enabled, this parameter is required; no value is assumed.

cibaPolicyId The CIBA request policy associated with the client.

PingFederate uses CIBA request policies to determine various aspects of CIBA authentication requests; for example, the maximum lifetime of authentication requests, the validity of unsigned login hint tokens, and the mapping configuration of identity hints.

Provide an existing CIBA policy

If this parameter is not provided and the CIBA grant type is enabled, PingFederate associates the client with the CIBA request policy has been designated as the default CIBA request policy on the OAuth Server > Request Policies screen.

cibaUserCodeSupported

Indicates whether the client supports user code.

The purpose of this code is to authorize the transmission of an authentication request to the user's authentication device.

A valid value is either true or false.

If this parameter is not provided and the CIBA grant type is enabled, user code support is not enabled.

Note that when user code support is enabled, the associated CIBA request policy must also be user code-enabled.

cibaRequireSignedRequests Indicates whether the client must transmit request parameters in a single, self-contained parameter. The parameter name is request. The value of the request parameter is a signed JWT whose claims represent the request parameters of the authorization request. The OpenID Connect specification calls this JWT a request object.

A valid value is either true or false.

If this parameter is not provided and the CIBA grant type is enabled, CIBA signed requests are not required.

Note that if CIBA signed requests are required, the client must also be configured with either the JWKS URL or the actual JWKS from the client.

cibaRequestObjectSigningAlgorithm The signing algorithm that the client must use to sign its request objects for transmission of request parameters.
Allowed values:
  • RS256 - RSA using SHA-256
  • RS384 - RSA using SHA-384
  • RS512 - RSA using SHA-512
  • ES256 - ECDSA using P256 Curve and SHA-256
  • ES384 - ECDSA using P384 Curve and SHA-384
  • ES512 - ECDSA using P521 Curve and SHA-512
  • PS256 - RSASSA-PSS using SHA-256
  • PS384 - RSASSA-PSS using SHA-384
  • PS512 - RSASSA-PSS using SHA-512
    Note:

    RSASSA-PSS signing algorithms require either a Java 11 runtime environment or an integration with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)

If this parameter is not provided and the CIBA grant type is enabled, the client can use any of the allowed signing algorithms.

Extended properties

extendedParameters Provide values for extended client metadata fields; for example:
{
  ...,
  "extendedParams": {
    "entry": [
      {
        "key": "ContactName",
        "value": {
          "elements": "J. Smith"
        }
      },
      {
        "key": "ContactNumbers",
        "value": {
          "elements": [
            "555-123-4567",
            "555-987-6543"
          ]
        }
      }
    ]
  },
  ...
}

This sample request provides a value for a single-valued client metadata field (ContactName) and multiple values for a multivalued client metadata field (ContactNumbers).

(Extended client metadata fields are defined on the System > Extended Properties screen.)

Sample JSON
{
  "client": [
    {
      "secret": "L1u508MfeZYTvR03kcpa6ezysNEspFEtzxSAIEOTll8AuNd2pnNqjkRdOXzfTFXc",
      "clientId": "SampleClient",
      "description": "This is a sample client.",
      "grantTypes": [
        "refresh_token",
        "authorization_code"
      ],
      "name": "Sample Client",
      "redirectUris": [
        "https://www.example.com/redirect1",
        "https://www.example.com/redirect2"
      ]
    }
  ]
}
Return codes
  • 200 – Success
  • 400 – Failed To Create Client

    The response contains details as to why the client creation failed.

  • 401 – Invalid Credentials

    The user does not exist or is not authorized to create a client.

  • 500 – Internal Server Error

    An unknown error has occurred.

PUT
Updates client details for a specified client.
Note:

You cannot update a client ID value. You can delete the client record and create a new one with a new client ID value.

JSON Parameters

The same parameters described for POST apply for PUT with one addition: forceSecretChange.

Use this parameter, set to true, in conjunction with the secret parameter to change a client pass phrase.

A valid value is either true or false.

If this parameter is not provided, a value of false is assumed.

Note:

If the secret parameter is used without a forceSecretChange parameter value of true, the secret value is ignored.

Sample JSON
{
  "client": [
    {
      "secret": "L1u508MfeZYTvR03kcpa6ezysNEspFEtzxSAIEOTll8AuNd2pnNqjkRdOXzfTFXc",
      "forceSecretChange": "true",
      "clientId": "SampleClient",
      "description": "This is a sample client.",
      "grantTypes": [
        "refresh_token",
        "authorization_code"
      ],
      "name": "Sample Client",
      "redirectUris": [
        "https://www.example.com/redirectOne",
        "https://www.example.com/redirectTwo"
      ]
    }
  ]
}
Return codes
  • 200 – Success

    The body contains a list of updated clients.

    400 – Failed To Update Client

    The response contains details as to why the client could not be updated.

  • 401 – Invalid Credentials

    The user does not exist or is not authorized to update a client.

  • 500 – Internal Server Error

    An unknown error has occurred.

GET
Retrieves details for all OAuth clients.
JSON Parameters
None.
Return codes
  • 200 – Success
    The body contains JSON data for all clients.
    Note:

    The parameter refreshRolling is not returned if the AS global setting is set for a client (the default).

  • 400 – Failed To Retrieve Clients

    The response contains details as to why clients could not be retrieved.

  • 401 – Invalid Credentials

    The user does not exist or is not authorized.

  • 500 – Internal Server Error

    An unknown error has occurred.

Endpoint: /pf-ws/rest/oauth/clients/<clientId>

This resource accepts the GET and DELETE methods.

GET
Retrieves details for the specified client ID.
JSON Parameters
None.
Return codes
  • 200 – Success
    JSON client parameters are included.
    Note:

    The parameter refreshRolling is not returned if the AS global setting is set for a client (the default).

  • 400 – Failed To Retrieve Client

    The response contains details as to why client could not be retrieved.

  • 401 – Invalid Credentials

    The user does not exist or is not authorized.

  • 500 – Internal Server Error

    An unknown error has occurred.

DELETE
Deletes records for the specified client ID.
JSON Parameters
None.
Return codes
  • 200 – Success
  • 400 – Failed To Delete Client

    The response contains details as to why client could not be deleted.

  • 401 – Invalid Credentials

    The user does not exist or is not authorized.

  • 405 – Method Not Allowed

    The client ID was not specified.

  • 500 – Internal Server Error

    An unknown error has occurred.

Logging

PingFederate records the actions performed via this endpoint in the runtime-api.log file. While the events themselves are not configurable, you may 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.