Generate ACME Credentials for Reseller Customers

SSL.com’s Reseller partners can now generate ACME credentials for their customers with the SWS API. This how-to describes the API endpoints a reseller must create to take advantage of this feature, and provides step-by-step instructions for generating a new set of credentials.

Reseller API Endpoints

Before getting started issuing ACME credentials to customers, resellers are expected to provide two API endpoints that SSL.com can call for authorization and certificate issuance. Resellers must also provide SSL.com with a callback URL (e.g. https://acme-hook.reseller.com in the examples below) that SSL.com’s RA will use when making these requests.

reseller_authorization

SSL.com will make a call to the reseller’s reseller_authorization endpoint to determine if a requested certificate should be issued (for example, if the customer’s account has sufficient funds). The request will include the user’s kid, the type and duration of the certificate being requested, and the validation method used:

POST https://acme-hook.reseller.com/reseller_authorization

{ 
  "kid": '2378c85a2d9b',
  'product': 'sslcom_dv',
  'duration': '365',
  'identifiers': { dns: ['example.com'] }
}

Successful Response (Order May Proceed)

A successful response, with a reseller indicating that an order is authorized and may proceed, must include a status code of 200 OK and a success value of true in the response body:

{
  "success": true
}

If a reseller authorizes an order as shown above, SSL.com’s RA will then check if the reseller can be billed for the purchase to determine of the order can go through. If a reseller authorizes an order but does not have sufficient funds to cover the certificate, a 90-day free certificate will be issued to the customers.

Failed Response (Order May Not Proceed)

A failed response should include an appropriate non-200 status code, for example:

• 403 Forbidden if a customer has insufficient funds with the reseller.
• 401 Unauthorized if the kid is not present in the reseller’s records.
• 500 Internal Server Error if something went wrong on the reseller’s side.

The response body for a failed order should include a value of false for success, and may also include an error_message that will be shown to the user:

{
  "success": "false",
  "error_message": "insufficient balance"
}

If error_message is empty, a general message reading “The order was not authorized” will be presented to the user.

receive_certificate

The receive_certificate endpoint is used for SSL.com to send the issued fullchain certificate to the reseller along with other information about the request:

POST https://acme-hook.reseller.com/receive_certificate

{
  "kid": "2378c85a2d9b",
  "product": "basicssl",
  "duration": "365",
  'identifiers': { dns: ['example.com', 'www.example.com'] },
  "cert": { 
    "body": <fullchain certificate>,
    "not_before"=>"2021-06-07T11:39:17.000-05:00",
    "not_after"=>"2021-09-19T11:36:24.000-05:00"
  }
}

Generate ACME Credentials

Once a reseller has supplied the API endpoints described above, they can follow the step-by-stem instructions below to generate ACME credentials for a customer:

1. First, you’ll need your SSL.com API credentials. Log into your SSL.com reseller dashboard and click the api credentials link.
   
2. Use the clipboard links to copy the Account/ACME Key and Secret Key associated with the account_admin role and paste them into a text editor.
   
3. Open a terminal window and enter a cURL command like the following. Replace ACCOUNT-KEY and SECRET-KEY with the values you collected in the previous step. Replace DESCRIPTION with some descriptive text about your customer such as their company name or user ID. Note that each DESCRIPTION that you use should be unique. Making repeated requests with the same description will return the credentials that were originally generated for the first request with that description.

   curl --location --request POST 'https://sws.sslpki.com/acme/create_credentials' \
   --header 'Content-Type: application/json' \
   --data-raw '{"account_key": "ACCOUNT-KEY", "secret_key": "SECRET-KEY", "description": "DESCRIPTION"}'

4. You should receive a JSON object with eab-kid and eab-hmac values that you can provide your customer to use when requesting certificates with ACME.

   {
       "response_type": "ok",
       "eab-kid": "2378c85a2d9b",
       "eab-hmac": "qTs1vE6SMcX3UgK5DtYbc48IYUd7wUr109eCslCdY3N"
   }

5. Newly generated credentials will also appear along with your reseller account’s other API and ACME credentials.