Renew your SAML 2.0 SSO certificate

Your SAML certificate is valid for a period of time determined by your Identity Provider. An administrator at your store should keep track of when your SAML certificate is due to expire, and renew the certificate in advance.

To check the expiration date on your certificate, use the getSamlSettings endpoint in the Admin API:

GET /ccadmin/v1/merchant/samlSettings  HTTP/1.1
Authorization: Bearer <access_token>

The response includes a certificate object with startDate and endDate properties. The endDate property indicates when the certificate will expire:

{
    "nameIdPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "requireEncryptedAssertions": false,
    "requireSignedResponse": false,
    "certificate": {
        "endDate": "2021-12-14T18:16:00.000Z",
        "startDate": "2020-12-15T18:16:00.000Z"
    },
    "signAuthnRequest": true,
    "spMetadata": "<service provider entity descriptor>",
    "links": [
        {
            "rel": "self",
            "href": "http://www.example.com:7002/ccadmin/v1/merchant/samlSettings"
        }
    ],
    "nameIdPolicyAllowCreate": true,
    "enabled": false
}

If your certificate will be expiring soon, use the renewSamlCertificate endpoint to renew it, Note that the request body should be empty:

POST /ccadmin/v1/merchant/renewSamlCertificate  HTTP/1.1
Authorization: Bearer <access_token>

If the request succeeds, the response has a status code of 200 to indicate the certificate has been renewed. The response payload includes the start date and end date for the new certificate:

{
    "endDate": "2022-12-10T17:41:09.000Z",
    "links": [
        {
            "rel": "self",
            "href": "http://www.example.com:7002/ccadmin/v1/merchant/renewSamlCertificate"
        }
    ],
    "startDate": "2021-12-11T17:41:09.000Z"
}

If the request is accepted but certificate renewal is still in progress, the response has a status code of 202. You can use the getSamlSettings endpoint later to check whether the certificate has been successfully renewed.