Note: Ping Identity periodically deprecates obsolete TLS protocols and cipher suites. To stay compatible with these changes, you should ensure that your platform stays within its support life cycle. For example, a Java application should use a Java version that is currently supported by the Java vendor.

The PingOne SSO for SaaS Apps Apps Customer Connection API conforms to the design principles of Representational State Transfer (REST), providing a set of resources you can use, and supporting the JSON data format. The API returns HTTP status codes with each resource response. If an error occurs, an error message is returned in the response. Resource request parameter values are required unless otherwise indicated. These parameter values need to be converted to UTF-8 and URL-encoded.

PingOne considers connections with the same idpId value as belonging to the same identity provider (IdP), so most parameter settings are shared across all connections using the same idpId. Updating the parameter settings on one connection applies the same changes to all connections with the same idpId.

The exception to this is the multiplexed parameter, which determines whether the IdP uses a single connection to PingOne or distinct connections to each of your applications. The multiplexed setting is specific to each application connection.

To use the Customer Connection API, you need the API credentials for your account. For information on retrieving these credentials, see Using the global REST API client credentials.

Note:

The saasid is a UUID that uniquely identifies an application connection.

To find the saasid, go to Applications > My Applications. The saasid for each application connection is in parentheses under the connection name.

Create a customer connection

Creates a connection between your service and a customer.

PUT https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/<idpId>

Request parameters

Parameter Description

applications (optional)
An array of one or more unique application saasids. For example:
["6964005a-6270-4a88-9ddc-0e6a4e05e51d", "338821d7-dd17-469f-a3c1-8025a0112ebe"]

If you include specific application values:

  • If the application is multiplexed SAML or OIDC, creates a connection to specified applications
  • If the application is non-multiplexed SAML, returns an error message
  • If the application is multiplexed or OIDC but disabled, returns an error message

If you don't include application values, creates a connection to all enabled applications with the specified idpId, as long as they are enabled and either multiplexed SAML or OIDC.

multiplexed (optional)

If true or not specified, creates multiplexed connections.

If false, creates non-multiplexed connections.

email

The email address for the customer administrator.

idpId

A unique identifier for the customer. See The idpId Parameter for more information.

entityId

A unique string used to identify the customer to us.

ssoEndpoint

The endpoint at the customer to which we will send SAML AuthnRequests.

Note:

The SSO binding is not configurable using the Customer Connection API. PingOne SSO for SaaS Apps will always send the AuthnRequest using the Redirect binding for connections created through the API.

sloEndpoint (optional)

The URL at the identity provider (IdP) to which PingOne sends SAML single logout (SLO) requests.

sloResponseEndpoint (optional)

The URL at the IdP to which PingOne sends SAML SLO responses.

sloBinding (optional)

Determines which binding type PingOne uses to send SAML SLO requests. Valid values are Redirect or POST.

If not specified, defaults to POST.

signAuthnRequest (optional)

If true, enables AuthnRequest signing.

If false or not specified, defaults to disabled.

signingCertificateData

The public certificate for the customer's signing certificate. The customer IdP uses this certificate to sign SAML assertions to PingOne. PingOne sees this as the verification certificate.

signingCertFingerprint (optional)

The signing certificate fingerprint that PingOne uses to sign the AuthnRequest or SLO request to the customer IdP. You can find the fingerprint value by expanding the certificate details in the Setup > Certificates menu. For more information, see View certificate details.

If not specified, designates the default signing certificate.

signingAlgorithm (optional)

If specified, sets signing algorithm to specified value. Valid values are:

  • RSA_SHA1
  • RSA_SHA256 (default)
  • RSA_SHA384
  • RSA_SHA512

If not specified, defaults to RSA_SHA256.

Response Parameters

None.

Status Codes Returned

Status Code Description

201 Created

 The resource has been created.

400 Bad Request

 The request was invalid. An accompanying error message explains why.

403 Forbidden

 The request was understood, but has been refused. An accompanying error message explains why.

404 Not Found

 No available application found with given parameters.

409 Conflict

 The resource requested to be created already exists.

Example

   PUT https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/exampleIdp.com
{
	"email": "admin@exampleIdp.com",
	"entityId": "example Identity Provider",
	"ssoEndpoint": "http://www.exampleIdp.com",
	"signingCertificateData": "MIIDkDCCAvmgAwIBAgIJAONZ/Sh8jJVaMA0GCSqGSIb3DQEBBQUAMIGNMQswCQYDVQQGEwJVUzER\
		nMA8GA1UECBMIQ29sb3JhZG8xDzANBgNVBAcTBkRlbnZlcjEiMCAGA1UEChMZRXhhbXBsZSBJZGVu\
		ndGl0eSBQcm92aWRlcjERMA8GA1UEAxMISm9obiBEb2UxIzAhBgkqhkiG9w0BCQEWFGFkbWluQGV4\
		nYW1wbGVJZHAuY29tMB4XDTExMTAyNjIyNDA1MFoXDTIxMTAyMzIyNDA1MFowgY0xCzAJBgNVBAYT\
		nAlVTMREwDwYDVQQIEwhDb2xvcmFkbzEPMA0GA1UEBxMGRGVudmVyMSIwIAYDVQQKExlFeGFtcGxl\
		nIElkZW50aXR5IFByb3ZpZGVyMREwDwYDVQQDEwhKb2huIERvZTEjMCEGCSqGSIb3DQEJARYUYWRt\
		naW5AZXhhbXBsZUlkcC5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMx6WsTrzwhi10De\
		nPvvTa/Ndle2+3ZLePGXE/0v1qmm8Pji8l0czcg8ner56KBgnt2gnJ5xGrN51zBjZi7Qg2cL3A5cQ\
		nErJdYNsc7Oedulmp6RnDInMX1sfn/kGc3L/zBdwrngQWv86vN3bawvtj5wYsc9OAG1+X1kQeDuyR\
		ne/NlAgMBAAGjgfUwgfIwHQYDVR0OBBYEFMDDtN8tPSFrVtUWcpc0mbtsge9UMIHCBgNVHSMEgbow\
		ngbeAFMDDtN8tPSFrVtUWcpc0mbtsge9UoYGTpIGQMIGNMQswCQYDVQQGEwJVUzERMA8GA1UECBMI\
		nQ29sb3JhZG8xDzANBgNVBAcTBkRlbnZlcjEiMCAGA1UEChMZRXhhbXBsZSBJZGVudGl0eSBQcm92\
		naWRlcjERMA8GA1UEAxMISm9obiBEb2UxIzAhBgkqhkiG9w0BCQEWFGFkbWluQGV4YW1wbGVJZHAu\
		nY29tggkA41n9KHyMlVowDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQBqagX/ZasSD0NP\
		nQnR3zDXAYJK87VO59mn21TLEYaKG9vcm+odQhc0XkwLR/PLMTv3GSV9dfC0F6QHogLpZe1W+oa7Q\
		n+7Utasnsgs4Kfp0s2jQaPnUJRpGKXFPyOJ17RkjJgubKcYnX+vYV13tBDq4cIIm68dqZZqzaXDau\n0Z3h2Q==",
}

Get a Customer Connection

Returns all available information about a customer connection.

   GET https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/<idpId>

Request Parameters

Parameter Description

application (optional)

If the application connection exists, returns only that connection's information.

If no application matches the saasid, returns all connections with the same idpId.

idpId

A unique identifier for the customer.

See The idpId Parameter for more information.

Response Parameters

Parameter Description

email

The email address for the customer administrator.

idpId

A unique identifier for the customer.

For more information, see The idpId Parameter.

entityId

A unique string used to identify the customer to us.

ssoEndpoint

The endpoint at the customer to which we will send SAML AuthnRequests.

Note:

The SSO binding is not configurable using the Customer Connection API. PingOne SSO for SaaS Apps will always send the AuthnRequest using the Redirect binding for connections created through the API.

signingCertificate

 The customer's public certificate for the customer's signing certificate (encoded in MIME Base64). PingOne uses this to sign SAML assertions.

multiplexed

Whether the connection is multiplexed.

sloEndpoint

The URL to which the connection sends SLO requests.

sloResponseEndpoint

The URL at the IdP to which PingOne sends SAML SLO responses.

sloBinding

The binding type the connection uses to send SLO requests.

signAuthnRequest

Whether the connection signs outgoing AuthnRequests.

signingAlgorithm

Which signing algorithm the connection uses to sign outgoing AuthnRequests.

signingCertFingerprint

Not provided in the GET response.

connectionsStatus

The customer connection status. Possible values are:

  • Active
  • Complete
  • Disabled
  • Disabled by Customer
  • Account Suspended

Status Codes Returned

Status Code Description
201 Created The resource has been created.
400 Bad Request The request was invalid. An accompanying error message explains why.
403 Forbidden The request was understood, but has been refused. An accompanying error message explains why.
404 Not Found No available application found with given parameters.
409 Conflict The resource requested to be created already exists.

Example

   GET https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/exampleIdp.com
[
	{
		"email": "admin@exampleIdp.com",
		"idpId": "exampleIdp.com",
		"entityId": "example Identity Provider",
		"ssoEndpoint": "http://www.exampleIdp.com",
		"signingCertificate": "MIIDkDCCAvmgAwIBAgIJAONZ/Sh8jJVaMA0GCSqGSIb3DQEBBQUAMIGNMQswCQYDVQQGEwJVUzER\
		nMA8GA1UECBMIQ29sb3JhZG8xDzANBgNVBAcTBkRlbnZlcjEiMCAGA1UEChMZRXhhbXBsZSBJZGVu\
		ndGl0eSBQcm92aWRlcjERMA8GA1UEAxMISm9obiBEb2UxIzAhBgkqhkiG9w0BCQEWFGFkbWluQGV4\
		nYW1wbGVJZHAuY29tMB4XDTExMTAyNjIyNDA1MFoXDTIxMTAyMzIyNDA1MFowgY0xCzAJBgNVBAYT\
		nAlVTMREwDwYDVQQIEwhDb2xvcmFkbzEPMA0GA1UEBxMGRGVudmVyMSIwIAYDVQQKExlFeGFtcGxl\
		nIElkZW50aXR5IFByb3ZpZGVyMREwDwYDVQQDEwhKb2huIERvZTEjMCEGCSqGSIb3DQEJARYUYWRt\
		naW5AZXhhbXBsZUlkcC5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMx6WsTrzwhi10De\
		nPvvTa/Ndle2+3ZLePGXE/0v1qmm8Pji8l0czcg8ner56KBgnt2gnJ5xGrN51zBjZi7Qg2cL3A5cQ\
		nErJdYNsc7Oedulmp6RnDInMX1sfn/kGc3L/zBdwrngQWv86vN3bawvtj5wYsc9OAG1+X1kQeDuyR\
		ne/NlAgMBAAGjgfUwgfIwHQYDVR0OBBYEFMDDtN8tPSFrVtUWcpc0mbtsge9UMIHCBgNVHSMEgbow\
		ngbeAFMDDtN8tPSFrVtUWcpc0mbtsge9UoYGTpIGQMIGNMQswCQYDVQQGEwJVUzERMA8GA1UECBMI\
		nQ29sb3JhZG8xDzANBgNVBAcTBkRlbnZlcjEiMCAGA1UEChMZRXhhbXBsZSBJZGVudGl0eSBQcm92\
		naWRlcjERMA8GA1UEAxMISm9obiBEb2UxIzAhBgkqhkiG9w0BCQEWFGFkbWluQGV4YW1wbGVJZHAu\
		nY29tggkA41n9KHyMlVowDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQBqagX/ZasSD0NP\
		nQnR3zDXAYJK87VO59mn21TLEYaKG9vcm+odQhc0XkwLR/PLMTv3GSV9dfC0F6QHogLpZe1W+oa7Q\
		n+7Utasnsgs4Kfp0s2jQaPnUJRpGKXFPyOJ17RkjJgubKcYnX+vYV13tBDq4cIIm68dqZZqzaXDau\n0Z3h2Q==",
		"status":"Active"
	}
]

Update a Customer Connection

Updates a connection between your service and a customer. Optional parameters will be updated only if they are included in the request.

   POST https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/<idpId>

Request Parameters

Parameter Description

applications (optional)

An array of one or more unique application saasids. For example:

["6964005a-6270-4a88-9ddc-0e6a4e05e51d", "338821d7-dd17-469f-a3c1-8025a0112ebe"]

Updates connections to specified applications.

If you don't include application values, updates connections to all applications with the specified idpId. If no connection with the specified idpId exists, returns an error message.

multiplexed (optional)

If true, changes the connection to multiplexed.

If false, changes the connection to non-multiplexed.

email

The email address for the customer administrator.

idpId

A unique identifier for the customer. Will not return an error message, but will not update the idpId.

entityId

A unique string used to identify the customer to us.

ssoEndpoint

The endpoint at the customer to which we will send SAML AuthnRequests.

Note:

The SSO binding is not configurable using the Customer Connection API. PingOne SSO for SaaS Apps will always send the AuthnRequest using the Redirect binding for connections created through the API.

sloEndpoint (optional)

The URL at the identity provider (IdP) to which PingOne sends SAML single logout (SLO) requests.

If included and left blank ("sloEndpoint":""), clears the setting.

sloResponseEndpoint (optional)

The URL at the IdP to which PingOne sends SAML SLO responses.

If included and left blank ("sloResponseEndpoint":""), clears the setting.

sloBinding (optional)

Determines which binding type PingOne uses to send SAML SLO requests.

Valid values are Redirect or POST.

signAuthnRequest (optional)

If true, enables AuthnRequest signing.

If false, defaults to disabled.

signingCertificateData

The public certificate for the customer's signing certificate. The customer IdP uses this certificate to sign SAML assertions to PingOne. PingOne sees this as the verification certificate.

signingCertFingerprint (optional)

The signing certificate fingerprint that PingOne uses to sign the AuthnRequest or SLO request to the customer IdP. You can find the fingerprint value by expanding the certificate details at Setup > Certificates

For more information, see View certificate details.

signingAlgorithm (optional)

If specified, sets signing algorithm to specified value. Valid values are:

  • RSA_SHA1
  • RSA_SHA256
  • RSA_SHA384
  • RSA_SHA512

Response Parameters

None.

Status Codes Returned

Status Code Description
200 OK Success.
400 Bad Request The request was invalid. An accompanying error message explains why.
403 Forbidden The request was understood, but has been refused. An accompanying error message explains why.
404 Not Found The requested URI is either invalid or the resource doesn't exist.

Example

   PUT https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/exampleIdp.com
{
	"email": "admin@exampleIdp.com",
	"entityId": "example Identity Provider",
	"ssoEndpoint": "http://www.exampleIdp.com",
	"signingCertificateData": "MIIDkDCCAvmgAwIBAgIJAONZ/Sh8jJVaMA0GCSqGSIb3DQEBBQUAMIGNMQswCQYDVQQGEwJVUzER\
		nMA8GA1UECBMIQ29sb3JhZG8xDzANBgNVBAcTBkRlbnZlcjEiMCAGA1UEChMZRXhhbXBsZSBJZGVu\
		ndGl0eSBQcm92aWRlcjERMA8GA1UEAxMISm9obiBEb2UxIzAhBgkqhkiG9w0BCQEWFGFkbWluQGV4\
		nYW1wbGVJZHAuY29tMB4XDTExMTAyNjIyNDA1MFoXDTIxMTAyMzIyNDA1MFowgY0xCzAJBgNVBAYT\
		nAlVTMREwDwYDVQQIEwhDb2xvcmFkbzEPMA0GA1UEBxMGRGVudmVyMSIwIAYDVQQKExlFeGFtcGxl\
		nIElkZW50aXR5IFByb3ZpZGVyMREwDwYDVQQDEwhKb2huIERvZTEjMCEGCSqGSIb3DQEJARYUYWRt\
		naW5AZXhhbXBsZUlkcC5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMx6WsTrzwhi10De\
		nPvvTa/Ndle2+3ZLePGXE/0v1qmm8Pji8l0czcg8ner56KBgnt2gnJ5xGrN51zBjZi7Qg2cL3A5cQ\
		nErJdYNsc7Oedulmp6RnDInMX1sfn/kGc3L/zBdwrngQWv86vN3bawvtj5wYsc9OAG1+X1kQeDuyR\
		ne/NlAgMBAAGjgfUwgfIwHQYDVR0OBBYEFMDDtN8tPSFrVtUWcpc0mbtsge9UMIHCBgNVHSMEgbow\
		ngbeAFMDDtN8tPSFrVtUWcpc0mbtsge9UoYGTpIGQMIGNMQswCQYDVQQGEwJVUzERMA8GA1UECBMI\
		nQ29sb3JhZG8xDzANBgNVBAcTBkRlbnZlcjEiMCAGA1UEChMZRXhhbXBsZSBJZGVudGl0eSBQcm92\
		naWRlcjERMA8GA1UEAxMISm9obiBEb2UxIzAhBgkqhkiG9w0BCQEWFGFkbWluQGV4YW1wbGVJZHAu\
		nY29tggkA41n9KHyMlVowDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQBqagX/ZasSD0NP\
		nQnR3zDXAYJK87VO59mn21TLEYaKG9vcm+odQhc0XkwLR/PLMTv3GSV9dfC0F6QHogLpZe1W+oa7Q\
		n+7Utasnsgs4Kfp0s2jQaPnUJRpGKXFPyOJ17RkjJgubKcYnX+vYV13tBDq4cIIm68dqZZqzaXDau\n0Z3h2Q==",
}

Disable a Customer Connection

Disables the customer connection and single sign-on (SSO) access.

   POST https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/disable/<idpId>

Request Parameters

Parameter Description

application (optional)

If you include specific saasid, changes only that connection.

If you don't include application values, changes connections to all applications with the specified idpId.

Response Parameters

None.

Status Codes Returned

Status Code Description
200 OK Success.
304 Not Modified The resource hasn't been modified. There was no new data to return.
403 Forbidden The request was understood, but has been refused. An accompanying error message explains why.
404 Not Found The requested URI is either invalid or the resource doesn't exist.

Example

   POST https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/disable/exampleIdp.com

Enable a Customer Connection

Enables the customer connection and SSO access.

   POST https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/enable/<idpId>

Request Parameters

Parameter Description

application (optional)

If you include specific saasid, changes only that connection.

If you don't include application values, changes connections to all enabled applications with the specified idpId.

Response Parameters

None.

Status Codes Returned
Status Code Description
200 OK Success.
304 Not Modified The resource hasn't been modified. There was no new data to return.
403 Forbidden The request was understood, but has been refused. An accompanying error message explains why.
404 Not Found The requested URI is either invalid or the resource doesn't exist.

Example

   POST https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/enable/exampleIdp.com

Delete a Customer Connection

Deletes all connections for an idpId.

DELETE https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/<idpid>

Request Parameters

Parameter Description

application (optional)

If you include specific saasid, deletes only that connection.

If you don't include application values, deletes all connections with the specified idpId.

Response Parameters

None.

Status Codes Returned

Status Code Description
200 OK Connections have been deleted.
404 Not Found Connections not found for the specified idpid and saasid.

Example

DELETE https://admin.pingone.com/web-portal/rest/saas/idp/2.0/spManaged/exampleIdp.com