Request

Endpoint: !applyClientAuthCert

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

Use the POST method for this endpoint.

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

Request parameters

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

Parameter Requirement Type Max.Length Description

loginName

required

string

64 chars

The account username.

This value is case sensitive.

loginPassword

required

string

128 chars

The account password.

This value is case sensitive.

csr

optional

string

32767 chars

Certificate Signing Request, Base64-encoded, with or without the -----BEGIN xxxxx----- and -----END xxxxx----- header and footer.

Required if you are applying for a certificate.

Minimum key size: 3072 bits.

days

optional

integer

Validity period in days.

The allowed values are: 365, 730, 1095.

If omitted, the value defaults to 365.

UserLoginNameForCert

optional

string

64 chars

Any active user of your account to authorize.

serialNumber

conditional

integer

34 digits

The serial number of the certificate to collect or authorize a user for.

Either certificateID or serialNumber must be provided if collecting a certificate or authorizing a user.

certificateID

conditional

integer

16 digits

The internal certificate ID to collect or authorize a user for.

Either certificateID or serialNumber must be provided if collecting a certificate or authorizing a user.

collect

optional

char

1 char

Indicates whether you want to collect the issued certificate.

The possible values are:

  • Y — Collect the issued certificate.

  • N — Do not collect the issued certificate.

If Y, the foreignOrderNumber parameter (if specified) must not have already been used for any order placed by this account.

responseType

optional

integer

Specifies the format of the returned certificate data.

The possible values are:

  • 0 — certificate only (collect must be Y)

  • 2 — PKCS7 (intermediates/roots) (collect must be Y)

If omitted, the value defaults to 0.

Sample request

curl --location 'https://secure.trust-provider.com/products/!applyClientAuthCert' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'loginName=yourLoginName' \
--data-urlencode 'loginPassword=yourPassword' \
--data-urlencode 'csr=yourBase64EncodedCSR' \
--data-urlencode 'days=365' \
--data-urlencode 'UserLoginNameForCert=yourUserLoginName' \
--data-urlencode 'serialNumber=yourSerialNumber' \
--data-urlencode 'certificateID=yourCertificateID' \
--data-urlencode 'collect=Y' \
--data-urlencode 'responseType=0'

Response

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

Any errorCode less than 0 indicates an error condition and the errorMessage provides more details.

The response is formatted in x-www-form-urlencoded format.

Response parameters

The response may contain the following parameters:

Parameter Description

errorCode

The numeric code indicating the result of the request.

See the list of Error codes.

errorMessage

The explanation of the error.

status

The result of the action.

The possible values:

  • 0 — The action was not completed.

  • 1 — The action was successfully completed.

Sample success responses

Sample response when collect is not set (default)
{
    "orderNumber": "123456",
    "status": {
        "applied": "Yes",
        "issued": "No",
        "addedToUser": "No"
    },
    "error": {
        "code": 0,
        "description": null,
        "item": null
    }
}
Sample response when collect=Y and responseType=0
{
    "orderNumber": "123456",
    "certificate": "-----BEGIN CERTIFICATE-----MIICyDCCAbACAQAwQDETMBEGA1UEAwwKdnBzLXFhLmNvbTELMAkGA1UEBhMCUk8x
DTALBgNVBAgMBElhc2kxDTALBgNVBAcMBElhc2kwggEiMA0GCSqGSIb3DQEBAQUA
...
zrdHmzmuRxr4dkaGulTS2ch+MvM8gx5Oq5xEjoUr+LISyFm1FNfL+MBbr/m1i6Xn
sxolqdzytjMLCvC8yzAEyNNbwMh+waiAZxQSvKAVwezADggVwLlfRuUEEls=-----END CERTIFICATE-----",
    "status": {
        "applied": "Yes",
        "issued": "Yes",
        "addedToUser": "Yes"
    },
    "error": {
        "code": 0,
        "description": null,
        "item": null
    }
}
Sample response when collect=Y and responseType=2
{
    "orderNumber": "123456",
    "certificate": "-----BEGIN PKCS7-----……….-----END PKCS7-----",
    "status": {
        "applied": "Yes",
        "issued": "Yes",
        "addedToUser": "Yes"
    },
    "error": {
        "code": 0,
        "description": null,
        "item": null
    }
}

Sample error response

{
    "error": {
        "code": -4,
        "description": "The value of the 'days' argument is invalid!",
        "item": "days"
    }
}

Error codes

The following table outlines error responses that may be returned by the applyClientAuthCert API. 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.

-3

The 'xxxx' argument is missing!

The required argument is missing from the request.

-4

The value of the 'xxxx' argument is invalid!

The argument value does not meet validation requirements.

-14

An unknown error occurred!

An unknown error occurred.

-16

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

The request has failed due to authentication issues.

-17

Request used GET rather than POST!

The request method should be POST.

-81

The order should include smart-card based product!

The order must include a smart-card based product. This error occurs if the product type is not supported for the requested operation.

-136

Wrong certificate string

The certificate string provided is invalid or does not match the expected format.