{ "openapi": "3.1.0", "info": { "title": "DigitalTrust Tools API", "version": "1.0.0", "description": "Free, public API for SSL/TLS, certificate and email-security checks, run by Sooma (Portugal). No authentication. Limit: 100 requests per hour per IP. Every endpoint accepts GET with query parameters or POST with a JSON body. Private keys are never accepted. Also available as an MCP server at https://digitaltrust.pt/mcp.", "contact": { "name": "Sooma", "email": "ajuda@sooma.pt", "url": "https://digitaltrust.pt/ferramentas/api/" }, "termsOfService": "https://sooma.com/pt-pt/termos-e-condicoes/" }, "servers": [ { "url": "https://digitaltrust.pt/api/v1" } ], "paths": { "/ssl/check": { "get": { "operationId": "check_ssl_get", "summary": "Check a server TLS certificate", "description": "Connects to a public host and returns the certificate, chain, trust status, hostname match, days to expiry, negotiated protocol and supported TLS versions (1.0 to 1.3).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "host", "in": "query", "required": true, "description": "Hostname, e.g. example.pt or mail.example.pt", "schema": { "type": "string" } }, { "name": "port", "in": "query", "required": false, "description": "TLS port", "schema": { "type": "integer", "enum": [ 443, 8443, 465, 993, 995, 636, 853, 4443, 5061, 6697 ] } } ] }, "post": { "operationId": "check_ssl", "summary": "Check a server TLS certificate", "description": "Connects to a public host and returns the certificate, chain, trust status, hostname match, days to expiry, negotiated protocol and supported TLS versions (1.0 to 1.3).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "description": "Hostname, e.g. example.pt or mail.example.pt" }, "port": { "type": "integer", "description": "TLS port", "default": 443, "enum": [ 443, 8443, 465, 993, 995, 636, 853, 4443, 5061, 6697 ] } }, "required": [ "host" ] } } } } } }, "/certificate/decode": { "get": { "operationId": "decode_certificate_get", "summary": "Decode X.509 certificates", "description": "Decodes one or more PEM certificates (a full chain is accepted) and returns subject, SANs, issuer, validity, validation type (DV, OV, EV, QWAC), key, fingerprints and OCSP URL.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "certificate", "in": "query", "required": true, "description": "PEM certificate(s), starting with -----BEGIN CERTIFICATE-----", "schema": { "type": "string" } } ] }, "post": { "operationId": "decode_certificate", "summary": "Decode X.509 certificates", "description": "Decodes one or more PEM certificates (a full chain is accepted) and returns subject, SANs, issuer, validity, validation type (DV, OV, EV, QWAC), key, fingerprints and OCSP URL.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate": { "type": "string", "description": "PEM certificate(s), starting with -----BEGIN CERTIFICATE-----" } }, "required": [ "certificate" ] } } } } } }, "/csr/decode": { "get": { "operationId": "decode_csr_get", "summary": "Decode a certificate signing request", "description": "Decodes a PEM CSR and returns subject, SANs, key type and size, signature algorithm, signature validity, public key fingerprint and warnings that would make a CA reject it.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "csr", "in": "query", "required": true, "description": "PEM CSR, starting with -----BEGIN CERTIFICATE REQUEST-----", "schema": { "type": "string" } } ] }, "post": { "operationId": "decode_csr", "summary": "Decode a certificate signing request", "description": "Decodes a PEM CSR and returns subject, SANs, key type and size, signature algorithm, signature validity, public key fingerprint and warnings that would make a CA reject it.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csr": { "type": "string", "description": "PEM CSR, starting with -----BEGIN CERTIFICATE REQUEST-----" } }, "required": [ "csr" ] } } } } } }, "/keys/match": { "get": { "operationId": "match_public_keys_get", "summary": "Check that a certificate and a CSR share the same key", "description": "Compares the SHA-256 fingerprints of the public keys in a certificate and a CSR. Private keys are never accepted by this API: compare them locally with \"openssl pkey -in key.pem -pubout | openssl sha256\".", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "certificate", "in": "query", "required": false, "description": "PEM certificate", "schema": { "type": "string" } }, { "name": "csr", "in": "query", "required": false, "description": "PEM CSR", "schema": { "type": "string" } } ] }, "post": { "operationId": "match_public_keys", "summary": "Check that a certificate and a CSR share the same key", "description": "Compares the SHA-256 fingerprints of the public keys in a certificate and a CSR. Private keys are never accepted by this API: compare them locally with \"openssl pkey -in key.pem -pubout | openssl sha256\".", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate": { "type": "string", "description": "PEM certificate" }, "csr": { "type": "string", "description": "PEM CSR" } } } } } } } }, "/ct/search": { "get": { "operationId": "search_certificate_transparency_get", "summary": "List valid certificates issued for a domain", "description": "Searches public Certificate Transparency logs (Cert Spotter, with crt.sh as fallback) and returns the certificates still valid for a domain and, optionally, its subdomains: names, issuer, validity, days left and revocation.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain, e.g. example.pt", "schema": { "type": "string" } }, { "name": "include_subdomains", "in": "query", "required": false, "description": "Include subdomains", "schema": { "type": "boolean" } } ] }, "post": { "operationId": "search_certificate_transparency", "summary": "List valid certificates issued for a domain", "description": "Searches public Certificate Transparency logs (Cert Spotter, with crt.sh as fallback) and returns the certificates still valid for a domain and, optionally, its subdomains: names, issuer, validity, days left and revocation.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain, e.g. example.pt" }, "include_subdomains": { "type": "boolean", "description": "Include subdomains", "default": true } }, "required": [ "domain" ] } } } } } }, "/caa/check": { "get": { "operationId": "check_caa_get", "summary": "Check CAA records", "description": "Reads the CAA records that apply to a domain (walking up to the parent domain) and says which certificate authorities (Actalis, Asseco, GlobalSign, DigiCert, Sectigo, Let's Encrypt) may issue normal and wildcard certificates.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain, e.g. example.pt", "schema": { "type": "string" } } ] }, "post": { "operationId": "check_caa", "summary": "Check CAA records", "description": "Reads the CAA records that apply to a domain (walking up to the parent domain) and says which certificate authorities (Actalis, Asseco, GlobalSign, DigiCert, Sectigo, Let's Encrypt) may issue normal and wildcard certificates.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain, e.g. example.pt" } }, "required": [ "domain" ] } } } } } }, "/caa/generate": { "get": { "operationId": "generate_caa_get", "summary": "Generate CAA records", "description": "Builds CAA records, in structured form and as zone-file lines, that authorise the chosen certificate authorities to issue for a domain.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain, e.g. example.pt", "schema": { "type": "string" } }, { "name": "cas", "in": "query", "required": false, "description": "Certificate authorities to authorise: actalis, asseco, globalsign, digicert, sectigo, letsencrypt, harica, or a CAA identifier such as actalis.it (comma-separated)", "schema": { "type": "string" } }, { "name": "wildcard", "in": "query", "required": false, "description": "\"same\" lets the same CAs issue wildcards; \"none\" forbids wildcard certificates", "schema": { "type": "string", "enum": [ "same", "none" ] } }, { "name": "iodef", "in": "query", "required": false, "description": "Email address for CA incident reports", "schema": { "type": "string" } } ] }, "post": { "operationId": "generate_caa", "summary": "Generate CAA records", "description": "Builds CAA records, in structured form and as zone-file lines, that authorise the chosen certificate authorities to issue for a domain.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain, e.g. example.pt" }, "cas": { "type": "array", "description": "Certificate authorities to authorise: actalis, asseco, globalsign, digicert, sectigo, letsencrypt, harica, or a CAA identifier such as actalis.it", "items": { "type": "string" }, "default": [ "actalis", "asseco" ] }, "wildcard": { "type": "string", "description": "\"same\" lets the same CAs issue wildcards; \"none\" forbids wildcard certificates", "default": "same", "enum": [ "same", "none" ] }, "iodef": { "type": "string", "description": "Email address for CA incident reports" } }, "required": [ "domain" ] } } } } } }, "/email/check": { "get": { "operationId": "check_email_security_get", "summary": "Check email authentication of a domain", "description": "Returns MX, SPF, DKIM (when a selector is given), DMARC with its parsed tags, BIMI, MTA-STS (record and published policy) and TLS-RPT for a domain.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "domain", "in": "query", "required": true, "description": "Domain, e.g. example.pt", "schema": { "type": "string" } }, { "name": "dkim_selector", "in": "query", "required": false, "description": "DKIM selector to test, e.g. default, google, selector1", "schema": { "type": "string" } } ] }, "post": { "operationId": "check_email_security", "summary": "Check email authentication of a domain", "description": "Returns MX, SPF, DKIM (when a selector is given), DMARC with its parsed tags, BIMI, MTA-STS (record and published policy) and TLS-RPT for a domain.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain, e.g. example.pt" }, "dkim_selector": { "type": "string", "description": "DKIM selector to test, e.g. default, google, selector1" } }, "required": [ "domain" ] } } } } } }, "/products": { "get": { "operationId": "list_ssl_products_get", "summary": "List SSL/TLS certificates and prices", "description": "Lists the SSL/TLS certificates sold by DigitalTrust (DV, OV, EV, QWAC, QWAC PSD2), with yearly prices in euros without VAT, coverage options, issuance time and the order page for each.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [] } }, "/order/url": { "get": { "operationId": "build_order_url_get", "summary": "Build a prefilled order link", "description": "Returns the price and a link to the DigitalTrust order page with the certificate already chosen. Orders are confirmed by a person on that page; this API does not place orders.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "type", "in": "query", "required": true, "description": "Certificate type", "schema": { "type": "string", "enum": [ "dv", "ov", "ev", "qwac", "psd2" ] } }, { "name": "coverage", "in": "query", "required": false, "description": "Coverage", "schema": { "type": "string", "enum": [ "unico", "multi", "wildcard" ] } }, { "name": "years", "in": "query", "required": false, "description": "Subscription length in years, paid upfront (discounts: 2y 15%, 3y 17%, 4y 20%, 5y 25%)", "schema": { "type": "integer", "enum": [ 1, 2, 3, 4, 5 ] } } ] }, "post": { "operationId": "build_order_url", "summary": "Build a prefilled order link", "description": "Returns the price and a link to the DigitalTrust order page with the certificate already chosen. Orders are confirmed by a person on that page; this API does not place orders.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Certificate type", "enum": [ "dv", "ov", "ev", "qwac", "psd2" ] }, "coverage": { "type": "string", "description": "Coverage", "default": "unico", "enum": [ "unico", "multi", "wildcard" ] }, "years": { "type": "integer", "description": "Subscription length in years, paid upfront (discounts: 2y 15%, 3y 17%, 4y 20%, 5y 25%)", "default": 1, "enum": [ 1, 2, 3, 4, 5 ] } }, "required": [ "type" ] } } } } } } }, "components": { "schemas": { "Success": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object" } } }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }