--- title: PingOne SSO for SaaS Apps Customer Connection API description: You can use the PingOne SSO for SaaS Apps Customer Connection API to create or update application connections without using the admin console. component: pingoneforenterprise page_id: pingoneforenterprise:pingone_sso_for_saas_apps:p14saas_customer_connection_api canonical_url: https://docs.pingidentity.com/pingoneforenterprise/pingone_sso_for_saas_apps/p14saas_customer_connection_api.html revdate: December 30, 2022 section_ids: request-parameters: Request parameters response-parameters: Response Parameters status-codes-returned: Status Codes Returned example: Example request-parameters-2: Request Parameters response-parameters-2: Response Parameters status-codes-returned-2: Status Codes Returned example-2: Example request-parameters-3: Request Parameters response-parameters-3: Response Parameters status-codes-returned-3: Status Codes Returned example-3: Example request-parameters-4: Request Parameters response-parameters-4: Response Parameters status-codes-returned-4: Status Codes Returned example-4: Example request-parameters-5: Request Parameters response-parameters-5: Response Parameters example-5: Example delete-a-customer-connection: Delete a Customer Connection request-parameters-6: Request Parameters response-parameters-6: Response Parameters status-codes-returned-5: Status Codes Returned example-6: Example --- # PingOne SSO for SaaS Apps Customer Connection API You can use the PingOne SSO for SaaS Apps Customer Connection API to create or update application connections without using the admin console. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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](p14saas_use_rest_api_client_credentials.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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/ ``` ## 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 messageIf 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](p14saas_finding_idpid_value.html) 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. 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](p14saas_view_certificate_details.html).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/ ``` ## 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](p14saas_finding_idpid_value.html) for more information. | ## Response Parameters | Parameter | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `email` | The email address for the customer administrator. | | `idpId` | A unique identifier for the customer.Learn more in [The `idpId` Parameter](p14saas_finding_idpid_value.html). | | `entityId` | A unique string used to identify the customer to us. | | `ssoEndpoint` | The endpoint at the customer to which we will send SAML AuthnRequests. 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/ ``` ## 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. The SSO binding isn't 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](p14saas_view_certificate_details.html). | | `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/ ``` ## 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/ ``` ## 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/ ``` ## 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 ```