Skip to main content
Version: 4.42

API reference — Certificate management

Overview​

Certificates are the core resource in Redtrust. This page covers the most relevant methods for managing the certificate lifecycle through the API: assigning users to certificates, updating their properties, changing their status, deleting them, and querying them.

Before you start​

Before testing these methods, you need to set up SoapUI.

important

The <!--Optional:--> comments that appear in SOAP requests are generated automatically and may incorrectly mark required fields as optional.

This documentation explicitly states which fields are required or optional. Always trust this documentation.

Assign a user to a certificate​

AddCertificateUser​

Creates a certificate-type user in a domain. This user type authenticates against Redtrust using a digital certificate instead of a username and password.

NameTypeRequiredDescription
domainIdintegerYesID of the domain where the user is created. Find the value in ListDomains.
usernamestringYesUsername. Accepts letters (A-Z, a-z), numbers (0-9) and the characters -, _ and . as separators.
namestringYesFull name of the user.
emailstringYesEmail address of the user. Must be a valid email format.
activebooleanYesWhether the account is active (true) or disabled (false).
issuerIdsarray of integersNo*IDs of local CA certificates that must appear in the user's certificate chain. Find the values in ListCACertificates using certType=LOCAL_CA_ROOT.
certDirectiveIdsarray of integersNo*IDs of certificate directives that the user's certificate must comply with. Find the values in ListCertificateDirectives.
certAttributesarray of CertificateAttributeDataNo*Certificate attributes that the user's certificate must match. Each element includes: id (attribute type, from ListCertificateAttributes), name (attribute name, from ListCertificateAttributes), type (comparison operator: EXISTS, IS_EQUAL, NOT_EXISTS, NOT_EQUALS, CONTAINS), and value (the value to match; not required for EXISTS and NOT_EXISTS).

(*) You must provide at least one of these three fields. If all three are omitted, the server returns an error.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:rtad="http://schemas.datacontract.org/2004/07/RTAdminService.Types">
    <soap:Header/>
    <soap:Body>
        <urn:AddCertificateUser>
            <urn:domainId>2</urn:domainId>
            <urn:username>john.garcia</urn:username>
            <urn:name>John García</urn:name>
            <urn:email>john.garcia@example.com</urn:email>
            <urn:active>true</urn:active>
            <urn:issuerIds>
                <arr:int>5</arr:int>
            </urn:issuerIds>
            <urn:certDirectiveIds>
                <arr:int>1</arr:int>
            </urn:certDirectiveIds>
            <urn:certAttributes/>
        </urn:AddCertificateUser>
    </soap:Body>
</soap:Envelope>

EditCertificateUser​

Updates an existing certificate-type user in a domain. The array fields (issuerIds, certDirectiveIds, certAttributes) replace the current values entirely — omitting one clears it.

NameTypeRequiredDescription
domainIdintegerYesID of the domain where the user exists. Find the value in ListDomains.
userIdintegerYesID of the certificate user to update. This is the value returned in ResultData by AddCertificateUser.
namestringYesFull name of the user.
emailstringYesEmail address of the user. Must be a valid email format.
activebooleanYesWhether the account is active (true) or disabled (false).
issuerIdsarray of integersNo*IDs of local CA certificates that must appear in the user's certificate chain. Find the values in ListCACertificates using certType=LOCAL_CA_ROOT.
certDirectiveIdsarray of integersNo*IDs of certificate directives that the user's certificate must comply with. Find the values in ListCertificateDirectives.
certAttributesarray of CertificateAttributeDataNo*Certificate attributes that the user's certificate must match. Same structure as in AddCertificateUser.

(*) You must provide at least one of these three fields. If all three are omitted, the server returns an error.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <soap:Header/>
    <soap:Body>
        <urn:EditCertificateUser>
            <urn:domainId>2</urn:domainId>
            <urn:userId>42</urn:userId>
            <urn:name>John García</urn:name>
            <urn:email>john.garcia@example.com</urn:email>
            <urn:active>true</urn:active>
            <urn:issuerIds>
                <arr:int>5</arr:int>
            </urn:issuerIds>
            <urn:certDirectiveIds>
                <arr:int>1</arr:int>
            </urn:certDirectiveIds>
            <urn:certAttributes/>
        </urn:EditCertificateUser>
    </soap:Body>
</soap:Envelope>

Update a certificate​

EditCertificate​

Updates local properties of a certificate. Most fields are write operations — the value you send replaces what is currently stored, so you must send the full desired state in every request, not just the fields you want to change. Exceptions are described in the table below.

NameTypeRequiredDescription
certIdintegerYesID of the certificate to update. Find the value in the certificateHandler field returned by ListCertificates.
aliasstringNoDescriptive name for the certificate visible in the admin console. Sending an empty value clears the existing alias.
commentstringNoFree-text comment about the certificate. Sending an empty value clears the existing comment.
requirePinbooleanYesWhether the certificate requires a PIN to be used. Send false to remove the current PIN.
pinstringNoNew PIN for the certificate. Send empty or null to keep the current PIN. Only send this parameter when you want to change it.
requireUsageReasonbooleanYesWhether the certificate requires the user to enter a usage reason.
activebooleanYesWhether the certificate is active (true) or disabled (false).
ownerUIDstringNoUID of the certificate owner. Send an empty string to remove the current owner. Send null to keep the current owner.
userPinPolicyCertificateUserPinPolicyYesUser PIN policy: NO_USER_PIN, ASK_USER_PIN, FORCE_ASK_USER_PIN.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:EditCertificate>
            <urn:certId>14</urn:certId>
            <urn:alias>Signature certificate - Accounting</urn:alias>
            <urn:comment>Renewed March 2026</urn:comment>
            <urn:requirePin>false</urn:requirePin>
            <urn:pin></urn:pin>
            <urn:requireUsageReason>false</urn:requireUsageReason>
            <urn:active>true</urn:active>
            <urn:ownerUID></urn:ownerUID>
            <urn:userPinPolicy>NO_USER_PIN</urn:userPinPolicy>
        </urn:EditCertificate>
    </soap:Body>
</soap:Envelope>

Reset certificate PIN​

ResetPin​

Resets the PIN of a certificate and sends an email to the owner so they can choose a new one. Requires SMTP to be configured on the server.

NameTypeRequiredDescription
certIdintegerYesID of the certificate. Find the value in the certificateHandler field returned by ListCertificates.
emailstringYesEmail address of the certificate owner. The PIN reset notification is sent to this address.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ResetPin>
            <urn:certId>14</urn:certId>
            <urn:email>john.garcia@example.com</urn:email>
        </urn:ResetPin>
    </soap:Body>
</soap:Envelope>

Enable or disable certificates​

ChangeCertificatesStatus​

Changes the active or inactive status of one or more certificates at once.

NameTypeRequiredDescription
certIdsarray of integersYesIDs of the certificates to update. Find the values in the certificateHandler field returned by ListCertificates. You can send multiple IDs as shown in the example.
statusbooleanYesStatus to apply: active (true) or inactive (false).
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <soap:Header/>
    <soap:Body>
        <urn:ChangeCertificatesStatus>
            <urn:certIds>
                <!--Zero or more repetitions:-->
                <arr:int>243</arr:int>
                <arr:int>244</arr:int>
            </urn:certIds>
            <urn:status>true</urn:status>
        </urn:ChangeCertificatesStatus>
    </soap:Body>
</soap:Envelope>

Delete certificates​

DeleteCertificate​

Permanently deletes one or more certificates from the system.

NameTypeRequiredDescription
certIdsarray of integersYesIDs of the certificates to delete. Find the values in the certificateHandler field returned by ListCertificates. You can send multiple IDs as shown in the example.
certTypeCertificateTypeYesType of the certificates to delete. All IDs in certIds must belong to the same type. Values: CA_ROOT, PRIVATE, PUBLIC_KEY_EMAIL, LOCAL_CA_ROOT, PRELOADED.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <soap:Header/>
    <soap:Body>
        <urn:DeleteCertificate>
            <urn:certIds>
                <!--Zero or more repetitions:-->
                <arr:int>14</arr:int>
                <arr:int>15</arr:int>
            </urn:certIds>
            <urn:certType>PRIVATE</urn:certType>
        </urn:DeleteCertificate>
    </soap:Body>
</soap:Envelope>

Retrieve certificate information​

ListCertificates​

Returns a paginated list of certificates with their main data.

NameTypeRequiredDescription
viewTypeCertificatesViewTypeYesFilters certificates by status. Values: ViewAll, ViewExpired, ViewNotExpired, ViewWithOwner, ViewWithoutOwner, ViewActive, ViewInactive, ViewAssignable, ViewNoAssignable, ViewRenewal.
filterstringYesText that results must contain. If empty, returns all.
numBlockintegerYesBlock number to return. Starts at 0.
orderColumnOrderCertificatesColumnYesColumn used to sort results: ORDER_BY_NAME, ORDER_BY_ACTIVE, ORDER_BY_EXPIRATION_DATE, ORDER_BY_TOTAL_USES, ORDER_BY_DATETIME_LAST_USAGE.
orderTypeOrderTypeYesSort direction: ORDER_ASCENDING or ORDER_DESCENDING.

Results are returned in blocks of 1000 items. Use numBlock (starting at 0) to paginate through results. Divide TotalItems from the response by 1000 and round up to get the total number of blocks.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ListCertificates>
            <urn:viewType>ViewAll</urn:viewType>
            <urn:filter></urn:filter>
            <urn:numBlock>0</urn:numBlock>
            <urn:orderColumn>ORDER_BY_EXPIRATION_DATE</urn:orderColumn>
            <urn:orderType>ORDER_DESCENDING</urn:orderType>
        </urn:ListCertificates>
    </soap:Body>
</soap:Envelope>

GetCertificateData​

Returns detailed data for a specific certificate.

NameTypeRequiredDescription
certIdintegerYesID of the certificate. Find the value in the certificateHandler field returned by ListCertificates.
certTypeCertificateTypeYesType of the certificate. Values: CA_ROOT, PRIVATE, PUBLIC_KEY_EMAIL, LOCAL_CA_ROOT, PRELOADED.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:GetCertificateData>
            <urn:certId>14</urn:certId>
            <urn:certType>PRIVATE</urn:certType>
        </urn:GetCertificateData>
    </soap:Body>
</soap:Envelope>

ListCACertificates​

Returns the list of CA certificates of a given type. Use this method to obtain valid IDs for the issuerIds parameter in AddCertificateUser.

NameTypeRequiredDescription
certTypeCertificateTypeYesType of CA certificates to list. Valid values: CA_ROOT, LOCAL_CA_ROOT, PUBLIC_KEY_EMAIL.
filterstringNoText that results must contain. If empty, returns all.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ListCACertificates>
            <urn:certType>LOCAL_CA_ROOT</urn:certType>
            <urn:filter></urn:filter>
        </urn:ListCACertificates>
    </soap:Body>
</soap:Envelope>

ListCertificateAttributes​

Returns the list of certificate attribute types available in the system. Use this method to obtain valid id values for the certAttributes parameter in AddCertificateUser.

NameTypeRequiredDescription
filterstringNoText that results must contain. If empty or omitted, returns all attributes.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ListCertificateAttributes>
            <urn:filter></urn:filter>
        </urn:ListCertificateAttributes>
    </soap:Body>
</soap:Envelope>

Certificate directives​

AddCertificateDirective​

Creates a new certificate directive. Use this method to add directives that can then be assigned to certificate users via the certDirectiveIds parameter in AddCertificateUser.

NameTypeRequiredDescription
directivestringYesName of the directive to create.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:AddCertificateDirective>
            <urn:directive>Example directive</urn:directive>
        </urn:AddCertificateDirective>
    </soap:Body>
</soap:Envelope>

ListCertificateDirectives​

Returns the list of certificate directives configured in the system. Use this method to obtain valid IDs for the certDirectiveIds parameter in AddCertificateUser.

NameTypeRequiredDescription
filterstringNoText that results must contain. If empty or omitted, returns all directives.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:urn="urn:evolium:redtrust:administration:ws">
    <soap:Header/>
    <soap:Body>
        <urn:ListCertificateDirectives>
            <urn:filter></urn:filter>
        </urn:ListCertificateDirectives>
    </soap:Body>
</soap:Envelope>