Prepare: CSR and approvers

Step 0a — generate a CSR

POST /api/v1/ssls/generate-csr

Generates a CSR and matching private key on our side. Optional — you may bring your own CSR to configure instead.

Request

{
  "domainName": "apiname.com",
  "country": "TR",
  "state": "Istanbul",
  "locality": "Istanbul",
  "organization": "Apiname Ltd",
  "organizationUnit": "IT",
  "alternativeNames": ["www.apiname.com"]
}

Field	Required	Max	Notes
domainName	required	72	The certificate’s main name. For a wildcard certificate send *.apiname.com.
country	required	2	ISO 3166-1 alpha-2, uppercase.
state	required	50	State, province or region. Spell it out — no abbreviations.
locality	required	50	City.
organization	required	150	Legal entity name. For OV and EV certificates this must match official records exactly or vetting fails.
organizationUnit	required	150	Department, e.g. IT.
alternativeNames	optional	—	Extra names to embed in the CSR.

Response — 200

{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzEL...\n-----END CERTIFICATE REQUEST-----",
  "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhki...\n-----END PRIVATE KEY-----"
}

Store the private key now — there is no second chance

The private key is not kept unless you send it back in configure, and there is no endpoint that will return it later. Without it the issued certificate is useless and you will have to reissue.

Store it encrypted, alongside the CSR, against your customer’s record — before you make the next API call.

Errors

Code	Meaning and fix
Ssl:10001	Invalid domain name.
Ssl:10005	The domain name does not meet the required format. Wildcards must have the * as the leftmost label only.

Step 0b — inspect a CSR

POST /api/v1/ssls/check-csr

Decodes a CSR so you can confirm its contents before buying. Useful when the customer supplies their own.

Request

{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzEL...\n-----END CERTIFICATE REQUEST-----"
}

Response — 200

{
  "domainName": "apiname.com",
  "country": "TR",
  "state": "Istanbul",
  "locality": "Istanbul",
  "organization": "Apiname Ltd",
  "organizationUnit": "IT",
  "alternativeNames": "www.apiname.com",
  "isWildcard": false,
  "isSan": true
}

Use this to validate before charging

Check domainName matches what the customer ordered, and that isWildcard matches the package type. A mismatch discovered here costs nothing; the same mismatch discovered at configure has already cost the certificate fee and started the 7-day clock.

Errors

Code	Meaning and fix
Ssl:10004	The CSR could not be decoded. Check it includes the BEGIN/END lines and has not been line-wrapped incorrectly.

Step 0c — approver e-mail addresses

GET /api/v1/ssls/approvers

Lists the e-mail addresses the CA will accept as the domain’s approver, for e-mail-based validation.

Request

GET /api/v1/ssls/approvers?domainName=apiname.com&packageCode=POSITIVESSL

Parameter	Required	Notes
domainName	required
packageCode	conditional	Required if no certificate exists yet for this domain. Ignored once one does.

Response — 200

{
  "mails": [
    "admin@apiname.com",
    "administrator@apiname.com",
    "hostmaster@apiname.com",
    "postmaster@apiname.com",
    "webmaster@apiname.com"
  ]
}

What to do with it

Present this list to the customer and let them choose. The address they pick is what you send as approverMail. An address not on this list is rejected when authenticationType is Email.

If the customer has none of these mailboxes — common with a domain they just bought — use Cname or Http validation instead and skip this call.

Errors

Code	Meaning and fix
Ssl:10038	The approver list could not be retrieved from the CA. Retry, or use DNS/HTTP validation.
Ssl:10003	packageCode missing or unknown, and no certificate exists for the domain.