PingCentral API Reference
The PingCentral Administrative API is a REST-based interface that provides a programmatic way to make configuration changes to PingCentral as an alternative to using the administrative console.
The resources documented here display implementation details on that resource such as the available endpoints, the parameter and response models for the operation, and the model structure of the resources themselves. Each resource operation provides the ability to interact with the API.
PingCentral administrative API model
The PingCentral administrative API includes the following endpoints.
PingCentral workflow
-
In PingCentral, you can set up users. For more information, see Users.
-
In PingCentral, you can set up PingFederate and PingAccess development environments. For more information, see Environments.
-
In PingFederate and PingAccess, you can locate clients, connections, and applications that are worthy of replicating in new applications or adding to PingCentral.
-
In PingCentral, you can create OAuth, OpenID Connect, and SAML service provider templates based on these PingFederate clients and connections by saving PingFederate applications as templates. For more information, see Templates. You can also add existing PingFederate and PingAccess applications directly to PingCentral and assign them to application owners to manage. For more information, see Applications.
-
In PingCentral, application owners use your templates to create new OAuth, OIDC, and SAML service provider applications. You designate a name and description for each application as well as environment-specific information that makes it possible to run the application on the target environment. For more information, see Applications.
Applications
The application management API endpoints support operations to manage application resources, including designating an application owner and promoting the application from a development environment to production.
Applications data model
| Property | Description |
|---|---|
applicationOwners |
An array of strings that specifies the list of application owners. This is a required property. |
applicationOwnerGroups |
A string array of PingCentral groups that are application owners. This property is only applicable if PingCentral is configured in SSO mode. |
created |
A string that specifies the creation date for the application resource. |
description |
A string that provides a description of the resource. |
enabled |
A boolean that specifies whether the PingCentral application is enabled. |
environmentId |
A string that specifies the environment associated with the resource. |
id |
A string that specifies the resource identifier. |
modified |
A string that specifies the date the resource was last modified. |
name |
A string that specifies the name of the resource. This is a required property. |
pingcentralVersion |
A string that specifies the PingCentral software version. |
shouldUpdateToLatestTemplateVersion |
A boolean that returns true if the application should update to the latest template version. |
templateId |
A string that specifies the template associated with a PingCentral application, when applicable. If a templateId is provided, the environmentId must be null. |
templateVersion |
A read-only integer that stores the version of the template currently being used. |
type |
A string that specifies the application type. Options are OAuth, OIDC, SAML_20_SP, and PINGACCESS. This is a required property. |
unmanaged |
A boolean that specifies whether this application is not managed by PingCentral. |
usingOutdatedTemplate |
A boolean that returns true if the application is not using the latest template version. |
Client secret data model
| Property | Description |
|---|---|
clientSecret |
A string that specifies the encrypted client secret. |
Application promotion history data model
| Property | Description |
|---|---|
applicationId |
A string that specifies the ID of a promoted PingCentral application. This is a required property, specified in the request URL. |
environmentId |
A string that specifies the environment ID associated with the promotion of an application. This is a required property, specified in the request URL. |
environmentName |
A string that specifies the name of the environment associated with the promotion of an application. |
environmentShortCode |
A string that specifies the short code of the environment associated with the promotion of an application. |
id |
A string that specifies the ID associated with the promotion of a PingCentral application. |
name |
A string that specifies the name of an application at the time it was promoted. This is a required property. |
notPromotedInCurrentVersion |
A boolean that returns true if the promotion history was created in the previous version of PingCentral. |
outdatedVersion |
A boolean that specifies whether a promoted application was created using an outdated version of PingCentral. |
promoted |
The time and date when a PingCentral application was promoted. |
type |
A string that specifies the type of promoted PingCentral application. Options are OAuth, OIDC, SAML_20_SP, and PINGACCESS. This is a required property. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 204 | Successfully removed. No content. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 422 | The requested could not be completed because of validation error(s). |
READ Applications
READ One Application
CREATE Application
UPDATE Application
DELETE Application
CREATE Client Secret
READ Client Secret
READ Promotion History
Promote Application
Restore Application
READ Application Metadata
Certificates
Use the Certificates API endpoints to manage PingCentral certificates.
Data model
CertImportView - A representation of certificate data with an alias.
| Property | Type | Description |
|---|---|---|
| alias | string | The certificate alias. |
| fileData | string | The certificate data. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 204 | Successfully removed. No content. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 422 | The requested could not be completed because of validation error(s). |
READ Certificates
READ One Certificate
CREATE Certificate
UPDATE Certificate
DELETE Certificate
Certificate Utilities
The certificate management API endpoints support operations to manage certificate resources.
Data model
| Property | Description |
|---|---|
expires |
A string that specifies the date at which the certificate expires. |
fileData |
A string that specifies the certificate data. |
issuerDN |
A string that specifies the certificate's issuer distinguished name value. |
serialNumber |
A string that specifies the certificate's serial number. |
signatureAlgorithm |
A string that specifies the certificate's signature algorithm. |
subjectDN |
A string that specifies the certificate's subject distinguished name value. |
validFrom |
A string that specifies the time and date from which the certificate is valid. |
version |
An integer that specifies the certificate's version number. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 204 | Successfully removed. No content. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 422 | The requested could not be completed because of validation error(s). |
Convert Certificate
Encode Certificate
READ Certificate
Validate Certificate
Validate Key Pairs
CSRF Protection
The Cross Site Request Forgery (CSRF) API endpoint supports operations to manage CSRF protection against unauthorized HTTP requests submitted from a trusted users.
Data model
| Property | Description |
|---|---|
headerName |
A string that specifies the name of the HTTP header. |
parameterName |
A string that specifies the parameter name. |
token |
A string that specifies the CSRF token. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 500 | An unexpected error occurred. |
READ CSRF
Environments
The environments API endpoints support operations to create, read, update, and delete environment resources. Environments endpoints manage PingCentral environments as well as connected PingFederate and PingAccess environments.
Data model
| Property | Description |
|---|---|
description |
A string that provides a short description of the environment. |
id |
A string that specifies the environment associated with the resource. This field is required when updating an existing application as part of a PUT request. |
idpSigningCertificate |
A string that specifies the identity provider's signing certificate, which is used when promoting applications to this environment. |
idpSigningCertificateName |
A string that specifies the identity provider's signing certificate name, which is used when promoting applications to this environment. Maximum length is 255 characters. |
idpSigningCertificatePassword |
A string that specifies the identity provider's signing certificate password, which is used when promoting applications to this environment. |
name |
A string that specifies the name of the environment resource. Maximum length is 255 characters. This is a required property. |
paAuthenticationType |
A string that specifies the authentication type for the PingAccess API. Required if PingAccess is enabled. Possible values are PASSWORD or OAuth2. |
paClientId |
A string that specifies the client ID for the PingAccess API. Required if PingAccess is enabled and paAuthenticationType is set to OAuth2. |
paClientSecret |
A string that specifies the client secret for the PingAccess API. Required for adding environments if PingAccess is enabled and paAuthenticationType is set to OAuth2. |
paEnabled |
A boolean that specifies whether the environment is enabled for PingAccess. |
paHost |
A string that specifies the PingAccess host name. This is a required property if paEnabled is set to true. |
paPassword |
A string that specifies the PingAccess password. This is a required property if paEnabled is set to true. |
paPort |
A string that specifies the PingAccess server port number. This is a required property if paEnabled is set to true. |
paScopes |
A string list of space delimited scopes for the PingAccess API. Required if PingAccess is enabled and paAuthenticationType is set to OAuth2. |
paSkipVerification |
A boolean that specifies whether to bypass PingAccess version verification. |
paTokenEndpoint |
A string that specifies the token endpoint for validating PingAccess access token. Required if PingAccess is enabled and paAuthenticationType is set to OAuth2. |
paUsername |
A string that specifies the PingAccess administrator username. This is a required property if paEnabled is set to true. |
paVersion |
A string that specifies the PingAccess version number. |
pfAuthenticationType |
A string that specifies the authentication type for the PingFederate API. Possible values are PASSWORD or OAuth2. |
pfClientId |
A string that specifies the client ID for the PingFederate API. Required if pfAuthenticationType is set to OAuth2. |
pfClientSecret |
A string that specifies the client secret for the PingFederate API. Required for adding environments if pfAuthenticationType is set to OAuth2. |
pfHost |
A string that specifies the PingFederate host name. This is a required property. |
pfPassword |
A string that specifies the PingFederate administrator password. This is a required property. |
pfPort |
A string that specifies the PingFederate server port number. This is a required property. |
pfScopes |
A string list of space delimited scopes for the PingFederate API. Required if pfAuthenticationType is set to OAuth2. |
pfSkipVerification |
A boolean that specifies whether to bypass PingFederate version verification. |
pfTokenEndpoint |
A string that specifies the token endpoint for validating the PingFederate access token. Required if pfAuthenticationType is set to OAuth2. |
pfUsername |
A string that specifies the PingFederate administrator username. This is a required property. |
pfVersion |
A string that specifies the PingFederate version number. |
shielded |
A boolean that specifies whether services are shielded. When set to true, only administrators are allowed to promote applications to this environment. |
shortCode |
A string that specifies short code for the PingCentral environment (for example, TEST). Maximum length is 5 characters. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 204 | Successfully removed. No content. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 422 | The requested could not be completed because of validation error(s). |
READ Environments
READ One Environment
Create Environments
Validate Environment
UPDATE Environment
DELETE Environments
READ Environment With Runtime Information
Groups
The groups API endpoint supports operations to manage PingCentral groups.
Group data model
| Property | Type | Description |
|---|---|---|
| created | string | (Read-only) The time and date when the PingCentral group was created. |
| description | string | The description of the PingCentral group. Limited to 512 characters. |
| displayName | string | The display name of the PingCentral group. Limited to 255 characters. |
| id | string | (Read-only) The ID of the PingCentral group. This field is required when updating an existing group as part of a PUT request. |
| members | array[UserSummaryView] | A list of PingCentral users which are members of the group. |
| modified | string | (Read-only) The time and date when the PingCentral group was last modified. |
| name * | string | The name of the PingCentral group. Limited to 255 characters. |
| source * | string | The source of the group. Limited to 256 characters. |
UserSummaryView data model
| Property | Type | Description |
|---|---|---|
| firstName * | string | The first name of the user. |
| id | string | (Read-only) The ID of the PingCentral user. This field is ignored during a PUT operation. |
| lastName * | string | The last name of the user. |
| source * | string | The source of the user. Limited to 256 characters. |
| username * | string | The user name of the user. Limited to 78 characters. |
Response codes
| Code | Message |
|---|---|
| 200 | Success. |
| 201 | Successfully created. |
| 204 | Successfully removed. No content. |
| 400 | Bad Request. The request was improperly formatted or contained invalid fields. |
| 401 | Unauthorized. |
| 403 | Forbidden. |
| 404 | Not found. |
| 422 | Unprocessable entity. |
READ Groups
READ One Group
CREATE Group
Import Groups File
Validate Groups File
UPDATE Group
DELETE Group
Licenses
The licenses API endpoints support operations to read, upload, and validate license resources.
Data model
| Property | Description |
|---|---|
description |
A string that specifies the description of the PingCentral license. |
enforcementType |
An integer that specifies the enforcement type associated with the PingCentral license. |
expirationDate |
The date and time the PingCentral license will expire. |
id |
A string that specifies the ID associated with the resource. |
issueDate |
The date and time the PingCentral license was issued. |
name |
A string that specifies the name of the license resource. |
organization |
A string that provides the ID of the organization associated with this license. |
product |
A string that specifies the name of the product associated with this license. |
tier |
A string that specifies the license tier (for example, Trial). |
version |
A string that specifies the PingCentral license version. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 422 | The requested could not be completed because of validation error(s). |
| 500 | An unexpected error occurred. |
READ License
Upload License
Validate License
READ Service-level Agreement Status
UPDATE Service-level Agreement Acceptance
Metadata (Service Provider)
The connection metadata API endpoints support operations to create and read connection metadata resources.
Data model
| Property | Description |
|---|---|
acsUrl |
A string that specifies the service provider's Assertion Consumer Service (ACS) URL from the metadata XML file. |
attributeNames |
A list of attribute names from the metadata XML file (for example, subject, sn). |
certificate |
A string that specifies the service provider's certificate information from the metadata XML file. |
entityId |
A string that specifies the service provider's entity ID from the metadata XML file. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 422 | The requested could not be completed because of validation error(s). |
Upload Connection Metadata
Upload Connection Metadata from URL
Orchestration - PingAccess
The following orchestration API endpoints support operations to read connection PingAccess orchestration resources.
OIDC connection orchestration
PingCentral currently only orchestrates clients, OIDC policies, and access token managers. With PingCentral, OIDC client authentication can only occur if PingFederate is correctly configured with the appropriate data sources, password credential validators, authentication policies, policy contracts, policy contract mappings, persistent grants, and access token mappings. In this version, you cannot create clients with direct adapter mappings to an IdP adapter.
SAML connection orchestration
PingCentral currently only orchestrates the PingFederate IdP connection. With PingCentral, SAML connection authentication can only occur if PingFederate is correctly configured with the appropriate data sources, password credential validators, authentication policies, and policy contracts. In this version, you cannot create connections to an IdP adapter with direct adapter mappings.
PingAccess data model details
The following sections provide a summary of the PingAccess applications, dependent resources, and site authenticators data model properties.
PingAccess application data model
| Property | Description |
|---|---|
items.accessTokenValidator |
A string that specifies the access token validator associated with the application. |
items.agent |
A string that specifies the agent associated with the application. |
items.apiIdentityMapping |
A string that specifies the API identity mapping associated with the application. |
items.apiRuleSets |
An array of strings that specifies the API rule sets associated with the application. |
items.apiRules |
An array of strings that specifies the API rules associated with the application. |
items.application |
A string that specifies the JSON representation of the application (for example, OrderedMap { "id": 6, "enabled": true }). |
items.applicationType |
A string that specifies the type of application. (for example, Web). |
items.contextRoot |
A string that specifies the application's context root. |
items.description |
A string that specifies the application description. |
items.destination |
A string that specifies the application's destination type. Options are Agent and Site. |
items.enabled |
A boolean that specifies whether the PingAccess application is enabled. |
items.id |
A string that specifies the ID of the PingAccess application. |
items.name |
A string that specifies the name of the application. |
items.resources |
A string that specifies the resources associated with the application. |
items.site |
A string that specifies the site associated with the application. |
items.virtualHosts |
An array of strings that specifies the virtual hosts associated with the application. |
items.webIdentityMapping |
A string that specifies the Web identity mapping associated with the application. |
items.webRulesSets |
An array of strings that specifies the Web rule sets associated with the application. |
items.webRules |
An array of strings that specifies the Web rules associated with the application. |
items.webSessions |
A string that specifies the Web session associated with the application. |
PingAccess dependent resources token validator summaries data model
| Property | Description |
|---|---|
accessTokenValidatorSummaries.className |
A string that specifies the class name associated with an access token validator. |
accessTokenValidatorSummaries.configuration |
A string that specifies the configuration associated with an access token validator. |
accessTokenValidatorSummaries.id |
A string that specifies the ID of the access token validator. |
accessTokenValidatorSummaries.name |
A string that specifies the access token validator name. |
PingAccess dependent resources agent summaries data model
| Property | Description |
|---|---|
agentSummaries.description |
A string that specifies the PingAccess agent summary description. |
agentSummaries.hostname |
A string that specifies the agent's hostname. |
agentSummaries.id |
A string that specifies the ID of the agent. |
agentSummaries.name |
A string that specifies the agent's name. |
agentSummaries.port |
A string that specifies the agent's port number. |
PingAccess dependent resources identity mapping summaries data model
| Property | Description |
|---|---|
identityMappingSummaries.className |
A string that specifies the class name associated with an identity mapping. |
identityMappingSummaries.configuration |
A string that specifies the configuration associated with an identity mapping. |
identityMappingSummaries.id |
A string that specifies the ID of the identity mapping. |
identityMappingSummaries.name |
A string that specifies the identity mapping name. |
PingAccess dependent resources site authenticator summaries data model
| Property | Description |
|---|---|
siteAuthenticatorSummaries.description |
A string that specifies the PingAccess site authenticator summary description. |
siteAuthenticatorSummaries.id |
A string that specifies the ID of site authenticator. |
siteAuthenticatorSummaries.name |
A string that specifies the site authenticator's name. |
PingAccess dependent resources site summaries data model
| Property | Description |
|---|---|
siteSummaries.description |
A string that specifies the PingAccess site summary description. |
siteSummaries.id |
A string that specifies the ID of site. |
siteSummaries.name |
A string that specifies the site's name. |
siteSummaries.secure |
A boolean that specifies whether the site is expecting HTTPS connections. |
siteSummaries.siteAuthenticatorIds |
A list that specifies the site authenticators associated with the site. |
siteSummaries.targets |
A list of targets for the site. |
PingAccess dependent resources virtual hosts summaries data model
| Property | Description |
|---|---|
virtualHostSummaries.description |
A string that specifies the PingAccess virtual host summary description. |
virtualHostSummaries.host |
A string that specifies the virtual host's hostname. |
virtualHostSummaries.id |
A string that specifies the ID of the virtual host. |
virtualHostSummaries.port |
A string that specifies the virtual host's port number. |
PingAccess dependent resources web sessions summaries data model
| Property | Description |
|---|---|
webSessionSummaries.description |
A string that specifies the PingAccess web session summary description. |
webSessionSummaries.audience |
A string that specifies the web session's audience. |
webSessionSummaries.clientCredentials |
A string that specifies the mapping of a web session's client credentials. |
webSessionSummaries.clientId |
A string that specifies the OAuth client ID associated with the web session. |
webSessionSummaries.cookieDomain |
A string that specifies the domain associated with the PingAccess cookie. |
webSessionSummaries.cookieType |
A string that specifies the type of PingAccess cookie for example, encrypted). |
webSessionSummaries.httpOnlyCookie |
A boolean that specifies whether the HttpOnly flag is set on cookies that contain the PingAccess token. |
webSessionSummaries.id |
A string that specifies the ID of the web session. |
webSessionSummaries.name |
A string that specifies the web session name. |
webSessionSummaries.oidcLoginType |
A string that specifies the OpenID Connect login type associated with a web session. |
webSessionSummaries.sameSite |
A string that specifies the level of restriction for when cookies may be sent across sites. |
webSessionSummaries.scopes |
An array of strings that specifies the list of scopes associated with a web session. |
webSessionSummaries.secureCookie |
A boolean that specifies whether the PingAccess cookie must be sent using only HTTPS connections. |
webSessionSummaries.validateSessionIsAlive |
A boolean that specifies whether validation of the session with PingFederate occurs. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
READ PingAccess Applications
READ PingAccess Dependent Resources
READ PingAccess Site Authenticators
Orchestration - PingFederate
The following orchestration API endpoints support operations to read PingFederate orchestration resources.
OIDC connection orchestration
PingCentral currently only orchestrates clients, OIDC policies, and access token managers. With PingCentral, OIDC client authentication can only occur if PingFederate is correctly configured with the appropriate data sources, password credential validators, authentication policies, policy contracts, policy contract mappings, persistent grants, and access token mappings. In this version, you cannot create clients with direct adapter mappings to an IdP adapter.
SAML connection orchestration
PingCentral currently only orchestrates the PingFederate IdP connection. With PingCentral, SAML connection authentication can only occur if PingFederate is correctly configured with the appropriate data sources, password credential validators, authentication policies, and policy contracts. In this version, you cannot create connections to an IdP adapter with direct adapter mappings.
PingFederate data model details
The following sections provide a summary of the PingFederate client dependencies, client summaries, service provider connection details, and service provider connection summaries data model properties.
PingFederate client dependencies data model
| Property | Description |
|---|---|
atmsJson |
A string that specifies the Access Token Manager JSON associated with the PingFederate client. |
clientJson |
A string that specifies the client JSON associated with the PingFederate client. |
oidcPolicyJson |
A string that specifies the OIDC policy JSON associated with the PingFederate client. |
PingFederate client summary views data model
| Property | Description |
|---|---|
items.attributes |
An array of strings that specifies the list of extended OIDC attributes. |
items.client |
A string that specifies the client JSON for a client. |
items.clientId |
A string that specifies the client ID of a client. |
items.description |
A string that specifies the PingFederate client summary description. |
items.exclusiveScopes |
An array of strings that specifies the list of exclusive scopes for a client. |
items.grantTypes |
An array of strings that specifies the list of grant types for a client. |
items.name |
A string that specifies the client name. |
items.oidcPolicyName |
A string that specifies the name of the OIDC policy associated with a client. |
items.redirectUrls |
An array of strings that specifies the list of redirect URIs associated with a client. |
items.scopes |
An array of strings that specifies the list of restricted common scopes associated with a client. |
items.usedByPA |
A boolean that specifies whether the client is associated with a web session in PingAccess. |
PingFederate service provider connection details data model
| Property | Description |
|---|---|
authenticationPolicyContractDetails |
A string that specifies the authentication policy contract details for this client connection. |
authenticationPolicyContractDetails.description |
A string that specifies the authentication policy contract details for a PingFederate SAML SP connection. |
authenticationPolicyContractDetails.id |
A string that specifies the ID of the authentication policy contract. |
authenticationPolicyContractDetails.identityAttributeNames |
An array of strings that specifies the list of identity attribute names associated with the authentication policy contract. |
authenticationPolicyContractDetails.name |
A string that specifies the name of the authentication policy contract. |
authenticationPolicyContracts.description |
A string that specifies the authentication policy contract details for a PingFederate SAML SP connection. |
authenticationPolicyContracts.id |
A string that specifies the ID of the authentication policy contract. |
authenticationPolicyContracts.identityAttributeNames |
An array of strings that specifies the list of identity attribute names associated with the authentication policy contract. |
authenticationPolicyContracts.name |
A string that specifies the name of the authentication policy contract. |
connectionJson |
A string that specifies the connection JSON for the SAML application. |
PingFederate service provider connection summary data model
| Property | Description |
|---|---|
items.acsUrl |
A string that specifies the assertion consumer service (ACS) URL associated with a connection. |
items.authenticationPolicyContractAssertionMappings |
An array of strings that specifies the list of authentication policy contract assertion mappings for a connection. |
items.connection |
A string that specifies the connection JSON associated with a connection. |
items.description |
A string that specifies the PingFederate SAML SP connection summary. |
items.enabledProfiles |
An array of strings that specifies the list of the enabled profiles of a connection. |
items.entityId |
A string that specifies the entity ID associated with a connection. |
items.id |
A string that specifies the ID associated with a connection. |
items.incomingBindings |
An array of strings that specifies the list of the incoming bindings of a connection. |
items.name |
A string that specifies the name of a connection. |
items.protocol |
A string that specifies the protocol of a connection (for example, SAML20). |
items.spCertificate |
A string that specifies the service provider certificate associated with a connection. |
items.type |
A string that specifies the type of connection (for example, SP). |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
READ PingFederate SP Connection Details
READ PingFederate SP Connection Summaries
READ PingFederate Client Dependencies
READ PingFederate Client Summaries
READ PingFederate Signing Certificates
Session Login Management
The sessions API endpoints support operations to create, read, and delete session resources.
Session request query parameters
| query parameter | Description |
|---|---|
authenticated |
A booliean that specifies whether this is an authenticated session. |
authorities[0].authority |
An array string that lists the account login authorities. |
credentials |
An object that specifies the login credentials. |
details |
An object that specifies the session details. |
principal |
An object that specifies the session principal. |
Session token claims
| Claim | Description |
|---|---|
sub |
A string that specifies the subject of the session JWT. |
aud |
A string that audience of the session JWT. |
iss |
A string that specifies the issuer of the session JWT. |
iat |
The time and date the session JWT was issued. |
exp |
The time and date the session JWT expires. |
jti |
A unique identifier for the JWT. |
aty |
A list of authorities associated with the session JWT. |
oiat |
The time and date the session was originally issued. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 204 | Successfully removed. No content. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 500 | An unexpected error occurred. |
READ Session Information
CREATE Session (Login)
DELETE Session (Logout)
Session Management
The session API endpoints support operations to read and update session resources.
Data model
| Property | Description |
|---|---|
cookieName |
A string that specifies the name of the cookie containing the session JWT. This is a required property. |
keyRollIntervalHours |
An integer that specifies the lifetime in hours of the key used to encrypt the session cookie. This is a required property. |
maxIdleTimeSeconds |
An integer that specifies the maximum time in seconds a session is valid without activity. This is a required property. |
maxSessionTimeSeconds |
An integer that specifies the maximum time in seconds a session is valid. This is a required property. |
sessionUpdateIntervalSeconds |
An integer that specifies the minimum number of seconds between session cookie updates. This is a required property. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 422 | The requested could not be completed because of validation error(s). |
READ Sessions
UPDATE Session Settings
System
The system endpoints provide access to your PingCentral environment system-related configurations.
SSO
The SSO endpoint provides an operation to check the status of single sign-on.
Data model
| Property | Type | Description |
|---|---|---|
| ssoEnabled | boolean | Boolean set to True if SSO is enabled. |
Status codes
| Code | Reason |
|---|---|
| 200 | Success. |
| 401 | Unauthorized. |
| 403 | Forbidden. |
| 404 | Not found. |
READ SSO Status
Templates
The templates API endpoints support operations to create, read, update, and delete template resources. You can you create a PingCentral template based on an existing PingFederate or PingAcess application.
For PingAccess applications, the following property values are saved in the template:
- Virtual host information
- The context root
- Application type (Web, API, or Web + API)
- Destination type (site or agent)
- Web session information
- Identity mappings
- Resource defintions
- Rules and resource policies
For OAuth or OIDC, the following items are saved in the template:
- Client application
- Grant types
- ATM, if one exists
- Parent ATM, if one exists
- OIDC policy, if one exists
- Exclusive scopes referenced by the client
For SAML SP connections, the following items are saved in the template:
- Connection information
- Attribute names defined in the associated authentication policy contract
Data model
| Property | Description |
|---|---|
created |
A string that specifies the creation date for the template resource. |
description |
A string that provides a description of the resource. Limited to 512 characters. |
environmentId |
A string that specifies the ID of the environment containing the application from which the template was created. This is a required property. |
icon |
A string that specifies the icon to be displayed for the PingCentral template. Possible options are apps, badge, beaker, cog, device, globe, key, or puzzle. |
id |
A string that specifies the ID of the PingCentral template. This field is required when updating an existing template as part of a PUT request. |
modified |
A string that specifies the date the resource was last modified. |
name |
A string that specifies the name of the PingCentral template. Limited to 128 characters. |
pingcentralVersionAtCreation |
A string that specifies the version of PingCentral being used when the template was created. |
revisionSummaryViews |
An array list of all the revision summaries of the template. |
type |
A string that specifies the template type. Options are OAuth, OIDC, SAML_20_SP, and PINGACCESS. |
updateTemplateComment |
A string comment describing why a template has been updated. |
Revision summary data model
| Property | Description |
|---|---|
modified |
A string that specifies the time and date when the PingCentral template was last modified. |
modifiedBy |
A string that specifies the author of the template revision. |
revisionNumber |
An integer that specifies the version number of the template revision. |
updateTemplateComment |
A string comment describing why a template has been updated. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 204 | Successfully removed. No content. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 422 | The requested could not be completed because of validation error(s). |
READ All Templates
READ One Template
CREATE Template
UPDATE Template
DELETE Template
Restore Template
READ PingFederate Client summaries from Templates
READ One PingFederate Client Summary from Template
TLS Key Pairs
The TLS key pairs API endpoints support operations to retrieve the current Transport Layer Security (TLS)key pair, as well as to upload TLS PKCS12 key pairs for encrypting and decrypting data.
Data model
TlsKeyPairView - A TLS Key Pair.
| Property | Type | Description |
|---|---|---|
| certChain * | array[CertView] | (Read-only) TLS KeyPair Certificate Chain. |
| id * | string | (Read-only) TLS KeyPair Id. |
CertView - Information associated with a certificate.
| Property | Type | Description |
|---|---|---|
| alias | string | The alias for the certificate. |
| expires | string | (Read-only) The time and date at which the certificate expires. |
| fileData | string | (Read-only) The certificate's data. |
| id | string | (Read-only) The ID of the certificate. |
| issuerDN | string | (Read-only) The issuerDN of the certificate. |
| serialNumber | string | (Read-only) The serial number of the certificate. |
| signatureAlgorithm | string | (Read-only) The signature algorithm of the certificate. |
| status * | string | A high-level status for the certificate. |
| subjectAlternativeNames | array[string] | (Read-only) The certificate's subject alternative names. |
| subjectDN | string | (Read-only) The subjectDN of the certificate. |
| type | string | The type of certificate. |
| validFrom | string | (Read-only) The time and date from which the certificate is valid. |
| version | integer | (Read-only) The version of the certificate. |
TlsKeyPairImportView - A TLS Key Pair.
| Property | Type | Description |
|---|---|---|
| alias * | string | The alias for the private key and certificate chain. |
| filePassword * | string | The password for the PKCS12 file. |
| keyPassword * | string | The password for the private key. |
| pkcs12 * | string | The PKCS12 data. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 204 | Successfully removed. No content. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 422 | The requested could not be completed because of validation error(s). |
READ TLS Key Pair
Upload PKCS12 TLS Key Pair
Upload a Multipart TLS Key Pair PKCS12 File
Users
The users API endpoints support operations to create, read, update, and delete user resources. The users endpoints allow you to add users directly to PingCentral and manage their access through the application. To complete a user's profile in PingCentral, you need their first and last names, user names, and their assigned roles.
User view data model
| Property | Type | Description |
|---|---|---|
| confirmpassword * | string | The confirm password for the user. |
| firstName * | string | The first name of the user. |
| groups | array[GroupSummaryView] | A list of PingCentral groups which the user is a member of. This field is only applicable if PingCentral is configured in SSO mode. |
| id | string | (Read-only) The ID of the PingCentral user. This field is ignored during a PUT operation. |
| lastName * | string | The last name of the user. |
| password * | string | The password for the user. |
| role * | string | The role of the user. |
| source * | string | The source of the user. Limited to 256 characters. |
| username * | string | The user name of the user. Limited to 78 characters. |
GroupSummaryView data model
| Property | Type | Description |
|---|---|---|
| created | string | (Read-only) The time and date when the PingCentral group was created. |
| description | string | The description of the PingCentral group. Limited to 512 characters. |
| displayName | string | The display name of the PingCentral group. Limited to 255 characters. |
| id | string | (Read-only) The ID of the PingCentral group. This field is required when updating an existing group as part of a PUT request. |
| modified | string | (Read-only) The time and date when the PingCentral group was last modified. |
| name * | string | The name of the PingCentral group. Limited to 255 characters. |
| source * | string | The source of the group. Limited to 256 characters. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 201 | Successfully created. |
| 204 | Successfully removed. No content. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 500 | An unexpected error occurred. |
READ Users
CREATE User
READ One User
UPDATE User
DELETE User
Version
The version API endpoints support operations to read information about the PingCentral version.
Data model
| Property | Description |
|---|---|
version |
A string that specifies the PingCentral version. |
Response codes
| Code | Message |
|---|---|
| 200 | Successful operation. |
| 400 | The request could not be completed. |
| 401 | You do not have access to this resource. |
| 403 | You do not have permissions or are not licensed to make this request, or your license is exceeded. |
| 404 | The requested resource was not found. |
| 500 | An unexpected error occurred. |