Link Search Menu Expand Document


Create a Challenge to verify domain ownership. The CsrInfo MUST be created in a user’s subscription before a Challenge can be created.


Include an API Key as a query string parameter in the request URL

Request URL{api key}



Request Parameters

Name In Required Type Description
api-key query true string The user’s API Key for the subscription

Request Body

Add the CertificateOrder object to create a Challenge

Sample Request

    "hostname": "",
    "domainroot": "",
    "email": "",
    "password": "pwd1234",
    "challengeType": "DNS"


Post the CertificateOrder object to the API URL to create a Challenge. The Challenge object will be returned in the response. You must complete the challenge using the HTTP or DNS method to prove that you own the domain (hostname) that your are requesting the certificate for.


Name Type Description
201 Created Challenge The response body contains the specified Challenge object that was created

Sample Response

201 Created

    "challengeType": "DNS",
    "challengeTokens": [{
        "tokenName": "_acme-challenge",
        "tokenValue": "GpoAaCgrOFaXQjktSZ7OC4gFrs3z0hXQFE_1jg63XkA"
    "status": "pending",
    "certificateOrder": {
        "hostname": "",
        "domainroot": "",
        "email": "",
        "password": "pwd1234",
        "challengeType": "DNS",
        "orderUri": ""

Use the CertificateOrder in Certficate API

You must use the CertficateOrder object within the Challenge object as shown in the above response to post to the Certificate API to create the Certificate. The CertificateOrder object will contain the orderUri generated by the Challenge. This URI is used to validate the Challenge.

Completing the Challenge

You must use the tokenName and tokenValue to complete the Challenge to prove that you own the domain (hostname) that you are requesting the certificate for. The following methods can be used to validate the Challenge :


  • In your hosted website, you will need to create a folder named: .well-known/acme-challenge (note the dot at the start) in the root of your website

  • Add a extension-less file with the file name specified in the tokenName value. To this file, add the file content specified in the tokenValue

  • The following example image illustrates the file in the web root directory


Note: - for sites hosted in a Windows Server in IIS, extension-less files are not served by default. To solve this, add the following web.config file to the acme-challenge folder.

            <mimeMap fileExtension="." mimeType="text/plain"/>
  • The website and ‘well known’ file MUST be accessed publicly on the web


  • You must develop your own code or script to automate the placement of the validation file in the root of your website to automate the process.


  • In your management portal from your domain registrar (eg. GoDaddy, DNSimple, etc), add a DNS TXT record (name/host) as specified in the tokenName value (note the underscore ‘_’ at the start)

  • This is an example of a DNS TXT record in the ‘Azure DNS Zone’ domain management portal


  • This is another example of a DNS TXT record in the ‘GoDaddy’ domain management portal


  • Your domain registrar will have a similar portal to add your DNS TXT record

  • You must use the API’s from your domain provider to create the DNS TXT record to automate the process

Validating the Challenge

You will validate the Challenge by posting the CertificateOrder object contained within the Challenge object in the response shown above to the Certificate API. This will validate the Challenge and create the certificate once the validation passes.

  • For a failed Challenge, you will need to create a new Challenge to retry the validation. Only Challenges in the ‘pending’ state can be validated



CertificateOrder Object

Name Type Required Description
hostname string yes The hostname for the certificate
domainroot string yes *The domain root for the hostname
email string yes Email contact for certificate creator
password string yes Password for the certificate
challengeType string yes The method to use : “HTTP” or “DNS” to complete the challenge
orderUri string no The URI used to validate the challenge
  • domainroot - the domain root is the apex primary domain for the hostname. For instance, the domainroot for or or or * is


Challenge Object

Name Type Required Description
challengeType string yes The method to use : “HTTP” or “DNS” to complete the challenge
challengeTokens List{ChallengeToken} yes A list of ChallengeToken to complete the challenge
status string yes The status of the challenge : “pending”, “valid” or “invalid”
certificateOrder CertficateOrder yes The certificate order associated with the challenge

ChallengeToken Object

Name Type Required Description
tokenName string yes The name of the token used for the challenge
tokenValue string yes The value of the token used for the challenge


Name Code Description
Bad Request 400 Error details will be included as a string in the body of the response

Test the API

Note: Authorization in the Header is not supported for this API. Leave the authorization blank when testing. Use the API Key in the url parameter instead.

Test the API in the Developer’s Portal