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

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`	conditional	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`.

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

conditional

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

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.

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

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.
`-8`	`The CSR is missing a required field!`	The CSR does not include all required fields.
`-9`	`The CSR is not valid Base-64 data!`	The CSR must be encoded in valid Base-64 format.
`-10`	`The CSR cannot be decoded!`	The CSR could not be decoded properly.
`-11`	`The CSR uses an unsupported algorithm!`	The CSR’s algorithm is not supported.
`-12`	`The CSR has an invalid signature!`	The signature on the CSR is invalid.
`-13`	`The CSR uses an unsupported key size!`	The key size in the CSR is not supported.
`-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`.
`-25`	`The Common Name (Domain Name) in CSR may not contain a trailing whitespace!`	The Common Name in the CSR must not have trailing whitespace.
`-40`	`The CSR uses a key that is believed to have been compromised!`	The CSR’s key is on the compromised key list.
`-121`	`Dynamic — passes errorItem as the message.`	The error message is dynamic and will provide details about the error item of the response.
`-133`	`This 'xxxx' could not be assigned as it is already used for authentication.`	The specified value could not be assigned because it is already in use for authentication.
`-136`	`Wrong certificate string`	The certificate string provided is invalid or does not match the expected format.

-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.

-8

The CSR is missing a required field!

The CSR does not include all required fields.

-9

The CSR is not valid Base-64 data!

The CSR must be encoded in valid Base-64 format.

-10

The CSR cannot be decoded!

The CSR could not be decoded properly.

-11

The CSR uses an unsupported algorithm!

The CSR’s algorithm is not supported.

-12

The CSR has an invalid signature!

The signature on the CSR is invalid.

-13

The CSR uses an unsupported key size!

The key size in the CSR is not supported.

-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.

-25

The Common Name (Domain Name) in CSR may not contain a trailing whitespace!

The Common Name in the CSR must not have trailing whitespace.

-40

The CSR uses a key that is believed to have been compromised!

The CSR’s key is on the compromised key list.

-121

Dynamic — passes errorItem as the message.

The error message is dynamic and will provide details about the error item of the response.

-133

This 'xxxx' could not be assigned as it is already used for authentication.

The specified value could not be assigned because it is already in use for authentication.

-136

Wrong certificate string

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