Home API Documentation Security Tools API

About the Security Tools API

API Version: 1.9

The Security Tools API reads the TLS/SSL certificate a host is actually serving and hands it back as JSON. One HTTPS GET returns who the certificate was issued to and by, the validity window, the Subject Alternative Names it covers, its serial number and SHA-1 fingerprint, and the raw PEM - enough to check an expiry date, confirm a renewal reached production, or verify that the hostname you are calling is genuinely covered by the certificate answering for it.

Certificates are read from the host at request time rather than from a cache, so the response reflects what a client connecting right now would be presented with. Lookups need no API key. Any TCP port can be checked with the port parameter, so services that terminate TLS somewhere other than 443 - mail submission, staging listeners, internal load balancers - are inspected the same way as a public website.

This is the API for the Security Tools.

Endpoints

https://networkcalc.com/api/security/certificate/{hostname}

Retrieve the TLS/SSL certificate presented by a host. Returns the issuing chain details, validity window, alternate names, serial number, fingerprint and raw PEM for the certificate found on the given hostname and port.

Parameters

{hostname}

(Required) The hostname, domain name, or IP address to look up.

Example: https://networkcalc.com/api/security/certificate/example.com

port

(Optional) Specify the TCP port to use on the remote host.

Values: 0-65535

Example: https://networkcalc.com/api/security/certificate/example.com?port=8080

Response Format

CertificateResponse chevron_right

Response Codes

200
OK - Success.
400
NO_HOST_SPECIFIED - The {hostname} parameter was not specified.
400
INVALID_PORT - The port you specified is invalid or out of range.
400
TIMEOUT - The network connection timed out or no certificate exists.
400
UNSPECIFIED_ERROR - An unknown error occurred. Check all parameters and try again.

Examples

Example 1
Run this in the API
cURL Example
curl -X GET https://networkcalc.com/api/security/certificate/networkcalc.com
content_copy
PowerShell Example
Invoke-RestMethod https://networkcalc.com/api/security/certificate/networkcalc.com -Method GET | ConvertTo-Json
content_copy
Python Example
import requests
requests.get("https://networkcalc.com/api/security/certificate/networkcalc.com").json()
content_copy
Response
{
  "status": "OK",
  "meta": {
    "protocol": "https:",
    "hostname": "networkcalc.com",
    "port": 443
  },
  "certificate": {
    "protocol": "https:",
    "hostname": "networkcalc.com",
    "port": 443,
    "issued_to": "networkcalc.com",
    "issued_by": "R3",
    "valid_from": "2021-07-20T10:57:03.000Z",
    "valid_to": "2021-10-18T10:57:01.000Z",
    "alternate_names": [
      "DNS:networkcalc.com",
      "DNS:www.networkcalc.com"
    ],
    "serial_number": "049538841877FA41F48B7E30B7E56956DEE0",
    "fingerprint": "AE:C8:55:B7:92:35:C4:BB:6B:21:B8:4E:82:35:19:2F:EB:38:83:75",
    "raw": "-----BEGIN CERTIFICATE-----\nMIIFODCCBCCgAwIBAgISBJU4hBh3+kH0i34wt+VpVt7gMA0GCSqGSIb3DQEBCwUA\nMDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQD\nEwJSMzAeFw0yMTA3MjAxMDU3MDNaFw0yMTEwMTgxMDU3MDFaMBoxGDAWBgNVBAMT\nD25ldHdvcmtjYWxjLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB\nAL3INQZKw6UClvIBa8SEU1ODZ5IbLmVodB4k+PQ7OedNKoDaoYvkMkxQR4yabftJ\nw9KwlnwnHpocnjPoOJgcJWTiatI5EPypO9ED2nOX93QtvBrjBy8rvL8HLVR/k3mj\n1+X9fHlQPKFRm1SomsFK/AnE7QhObv53WTu+8zxvGC1ijbqsGJK27K/jc9LLnBeb\n+LHsHFuFbntYDUJJ/eICLgm5jLjTeSJzyPNm6fJIvRiEG7qJ/Pl1UhNKQn4dB2GR\nz2X4P4FlNZw9ZBJGWN53cvGKmmq1kLzjMJZRDX4XsBEQt7DBnl36oVFMQmYbDKSS\n8Jp+ZoxVw6Ze2KY71L7RmWcCAwEAAaOCAl4wggJaMA4GA1UdDwEB/wQEAwIFoDAd\nBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwDAYDVR0TAQH/BAIwADAdBgNV\nHQ4EFgQUEKm7LOJnyd2YGVegh/aYLFGeStwwHwYDVR0jBBgwFoAUFC6zF7dYVsuu\nUAlA5h+vnYsUwsYwVQYIKwYBBQUHAQEESTBHMCEGCCsGAQUFBzABhhVodHRwOi8v\ncjMuby5sZW5jci5vcmcwIgYIKwYBBQUHMAKGFmh0dHA6Ly9yMy5pLmxlbmNyLm9y\nZy8wLwYDVR0RBCgwJoIPbmV0d29ya2NhbGMuY29tghN3d3cubmV0d29ya2NhbGMu\nY29tMEwGA1UdIARFMEMwCAYGZ4EMAQIBMDcGCysGAQQBgt8TAQEBMCgwJgYIKwYB\nBQUHAgEWGmh0dHA6Ly9jcHMubGV0c2VuY3J5cHQub3JnMIIBAwYKKwYBBAHWeQIE\nAgSB9ASB8QDvAHUARJRlLrDuzq/EQAfYqP4owNrmgr7YyzG1P9MzlrW2gagAAAF6\nw8bN0QAABAMARjBEAiAm26xlO7/JFvgXSS70Xw2rLbYkmAiM7ItMOcdoCmXJaQIg\nM/RbvGwEdJys4PFKTDPeMsJ/+V8LUBbVMllEVn3fIycAdgB9PvL4j/+IVWgkwsDK\nnlKJeSvFDngJfy5ql2iZfiLw1wAAAXrDxs3dAAAEAwBHMEUCIQC0AceOooCkGv4J\ny/Nl9uZCDD6ovXOw3e27TuDgBXiC4QIgOAlHqWuQcWs6kDKr/vd6VKoTOXALGjJk\nRoBxvTPZivowDQYJKoZIhvcNAQELBQADggEBAEGoigzie5xSzIjTUV4Nyn5JljLn\nhd9J7zfp8R1sdVCDHaS9Wyy2RFc67h9KBg9iai/SuhNa8ifJGa8cZjjSl/sGBXha\nIm+/+R6Vdo74wgJnyzhF3f2vXZyz+d+hhinxCBkcg4TwtUilCEwTmcRCV9jjF7Rh\nfAOnxHsFFUXS9gq+BQMEGwyZl18lhrptpSvM+qsKT56RwmABqeCetCYts702rf7u\n52RqH2BhGR6YWUbZLtIG8EJCNUL1rK3QD0q374RkemEpUObybpaTVmZSg7IUCOaR\n9y4ko51BFSlbyA8hPxi7es+FBdZhMq8nqZj0r7TWNP3ppnv0soCYxSJ0Png=\n-----END CERTIFICATE-----"
  }
}
content_copy

Response Formats

{
  "status": "[string] The status of the request.",
  "certificate": {
    "issued_to": "[string] The host for which the certificate was issued.",
    "valid_from": "[date] The date on which the certificate became valid. Date format is ISO 8601.",
    "valid_to": "[date] The date on which the certificate expires. Date format is ISO 8601.",
    "alternate_names": "[array] Subnet Alternative Names (SANs), i.e., alternate hostnames.",
    "serial_number": "[string] The certificate's serial number, a unique identifier.",
    "fingerprint": "[string] The certificate's fingerprint, a computed has of the entire certificate",
    "raw": "[string] The certificate in its raw format. Includes newlines as '\n'"
  }
}
content_copy