Request

Endpoint: !AutoReplaceSMIME

https://secure.trust-provider.com/products/!AutoReplaceSMIME

Use the POST method for this endpoint.

Submit parameters in the x-www-form-urlencoded format.

Request parameters

The following table displays the required, optional, and conditional parameters.

Parameter Requirement Type Max.Length Description

loginName

required

string

64 chars

Your account username.

This value is case sensitive.

loginPassword

required

string

128 chars

Your account password.

This value is case sensitive.

orderNumber

required

string

128 chars

The order number of the certificate to replace.

csr

required

string

32767 chars

The PKCS#10, Base64-encoded certificate signing request, with or without the -----BEGIN xxxxx----- and -----END xxxxx----- header and footer.

If the Microsoft certificate template extension is provided in the CSR, it is automatically extracted and included in the certificate.

signatureHash

optional

string

64 chars

The preference for the signature hash algorithm to be used when issuing the certificate.

The allowed values are:

  • NO_PREFERENCE — Let Sectigo decide.

  • INFER_FROM_CSR — If the CSR was signed using sha1WithRSAEncryption or md5WithRSAEncryption, then PREFER_SHA1 is used. Otherwise, the value is PREFER_SHA2.

  • PREFER_SHA2 — If a suitable SHA-2 capable Sub-CA is available, Sectigo will use SHA-2. Otherwise, the value is PREFER_SHA1.

  • REQUIRE_SHA2 — If a suitable SHA-2 capable Sub-CA is available, Sectigo will use SHA-2. Otherwise, the issuance of the certificate will be blocked until a suitable Sub-CA becomes available.

If omitted, the value is NO_PREFERENCE.

caCertificateID

optional

integer

Use a particular CA certificate and key.

If specified, the caCertificateID parameter overrides Sectigo’s default choice of CA certificate and key to be used to issue this certificate.

This functionality is only available by special agreement with Sectigo.

revokeOldOrder

optional

char

1 char

Specify this parameter if the replaced order was issued and the associated certificate should be revoked.

The allowed values are:

  • Y — Revoke the issued certificate associated with the replaced order.

  • N — Do not revoke the issued certificate associated with the replaced order.

If omitted, the value defaults to N.

responseFormat

optional

integer

Specifies the response format.

The allowed values are:

  • 0 — Newline-delimited parameters.

  • 1 — URL-encoded parameters.

  • 2 — JSON format.

If omitted, the value defaults to 0.

languageName

conditional

string

2 chars

The language name, specified using an ISO639-1 two-character language code.

If omitted, the default language is English.

An account can contain multiple email templates in different languages for callback and enterprise authentication for instant issuance.

Contact Support for the email templates.

Only one of the following values may be specified:

  • en — English

  • zh — Chinese-Mandarin

  • da — Danish

  • nl — Dutch

  • fr — French

  • de — German

  • it — Italian

  • ja — Japanese

  • ko — Korean

  • pt — Portuguese

  • ru — Russian

  • es — Spanish

  • sv — Swedish

  • tr — Turkish

languageName is ignored when any of the following parameters are provided:

  • SMIMEVerificationTemplateID

  • SMIMERequestTemplateID

  • SMIMECollectionTemplateID

SMIMEVerificationTemplateID

optional

integer

Specifies the ID of the S/MIME Verification Template to be applied to the certificate.

If specified, SMIMEVerificationTemplateID overrides Sectigo’s default choice of the S/MIME Verification Email template to be used to validate the certificate.

Contact your account manager if you would like to set up one or more of your own S/MIME Verification Email templates that can be referenced by this parameter.

An account can contain multiple email templates.

Сontact Support for the S/MIME Verification Email templates.

SMIMEVerificationTemplateID prevails over languageName if both of these parameters are provided.

SMIMERequestTemplateID

optional

integer

Specifies the ID of the S/MIME Request Template to be applied to the certificate.

If specified, SMIMERequestTemplateID overrides Sectigo’s default choice of S/MIME Request Email template to be used to process the order.

Contact your account manager if you would like to set up one or more of your own S/MIME Request Email templates that can be referenced by this parameter.

An account can contain multiple email templates.

Contact Support for the S/MIME Request Email templates.

SMIMERequestTemplateID prevails over languageName if both of these parameters are provided.

SMIMECollectionTemplateID

optional

integer

Specifies the ID of the S/MIME Collection template to be applied to the certificate.

If specified, SMIMECollectionTemplateID overrides Sectigo’s default choice of S/MIME Collection Email template to be used. Contact your account manager if you would like to set up one or more of your own S/MIME Collection Email templates that can be referenced by this parameter.

An account can contain multiple email templates. Contact Support for the S/MIME Collection Email templates.

SMIMECollectionTemplateID prevails over languageName if both of these parameters are provided.

Sample request

curl --location 'https://secure.trust-provider.com/products/!AutoReplaceSMIME' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'loginName=login_name' \
--data-urlencode 'loginPassword=login_password' \
--data-urlencode 'orderNumber=1234567' \
--data-urlencode 'csr=-----BEGIN CERTIFICATE REQUEST-----
MIICyDCCAbACAQAwQDETMBEGA1UEAwwKdnBzLXFhLmNvbTELMAkGA1UEBhMCUk8x
DTALBgNVBAgMBElhc2kxDTALBgNVBAcMBElhc2kwggEiMA0GCSqGSIb3DQEBAQUA
...
zrdHmzmuRxr4dkaGulTS2ch+MvM8gx5Oq5xEjoUr+LISyFm1FNfL+MBbr/m1i6Xn
sxolqdzytjMLCvC8yzAEyNNbwMh+waiAZxQSvKAVwezADggVwLlfRuUEEls=
-----END CERTIFICATE REQUEST-----' \
--data-urlencode 'responseFormat=2' \
--data-urlencode 'REVOKEOLDORDER=Y'

Response

The request is successful when the server returns a response with the status code equals 0.

Any status code less than 0 indicates an error condition.

The list of codes and their descriptions can be found in Error codes.

Response with responseFormat=0

The MIME type will be text/plain for responseFormat=0 (by default).

The first line of the response represents a status code.

If the status code is less than 0, the second line contains an error message describing the error.

If the status code equals 0, the second line contains a new order number, which is returned if the replacement order has been created.

Response parameters

Response with responseFormat=1

Most of Sectigo’s API endpoints use URL-encoding for responses. AutoReplaceSMIME can be instructed to return responses in this format, simply by specifying responseFormat=1 in the request.

The MIME type will be application/x-www-form-urlencoded for responseFormat=1.

The following table displays the various parameters that can appear for responseFormat=1.

Parameter Description

errorCode

A numeric code that identifies the type of the error.

Always present in the response.

For more information, see Error codes.

errorMessage

A description of the error.

errorMessage is not present when status code = 0.

newOrderNumber

The S/MIME certificate order number generated by this replacement.

This parameter is only present in case the new order has been created.

Response with responseFormat set to 2

The MIME type will be application/json for responseFormat=2.

The following table displays the various parameters that can appear for responseFormat=2.

Parameter Description

errorCode

A numeric code that identifies the type of the error.

Always present in the response.

For more information, see Error codes.

errorMessage

A description of the error.

errorMessage is not present when status code = 0.

newOrderNumber

The S/MIME certificate order number generated by this replacement.

This parameter is only present if the new order has been created.

Sample success response

errorCode=0

Sample error response

The response with the error code -16.

errorCode=-16&errorMessage=Incorrect+login+details%2C+account+is+locked%2C+password+has+expired+or+your+source+IP+is+blocked.

Error codes

The following table outlines error responses returned by the AutoReplaceSMIME API endpoint. Each error response consists of an errorCode and an errorMessage indicating why the request failed.

Error Code Error Message Description

-1

Request was not made over HTTPS!

The request must use HTTPS protocol.

-2

Unrecognized argument!

The provided argument is not recognized.

-3

The 'xxxx' argument is missing!

A required argument is missing from the request.

-4

The value of the 'xxxx' argument is invalid!

The argument value does not meet validation requirements.

-13

The CSR uses an unsupported key size!

The key size in the CSR is not supported.

-16

Incorrect login details, account is locked, password has expired or your source IP is blocked.

Authentication has failed due to one of the specified reasons.

Verify your login credentials or check account restrictions.

-17

Request used GET rather than POST!

The request method should be POST.

-20

The Certificate has been Revoked!

The requested certificate is in a revoked state.

-22

The certificate is currently being issued!

The required certificate is in the process of being issued.

-42

Call limit reached! Please try again later

Indicates that the maximum number of API calls has been reached.

-91

Permission denied 'xxxx'

The user doesn’t have the permission to perform the specified action.

-136

Wrong certificate state

The certificate is not in a state that allows the requested operation.