Get certificate status

GET

/domains/{domain}/ssl/

curl --request GET \
  --url https://api.nsin.ir/domains/example.com/ssl/ \
  --header 'Authorization: Bearer <token>'

• Production

The domain’s current certificate — issuer, validity, SANs, key size — plus whether a manual re-issue is currently allowed, and coverage: proxied hostnames that are not on the certificate yet, with their retry state.

Authorizations

• bearerAuth
• apiKeyAuth

Parameters

Path Parameters

domain

required

string

The domain name (for example example.com) — not a numeric id.

Example

example.com

Responses

200

Certificate status.

Media type application/json

object

status

State of the domain’s own certificate: valid, expired, pending (an order is running), failed (the last order failed; see failure_count and next_retry_at) or none (no certificate yet).

string

Allowed values: valid expired pending failed none

expires_at

End of the certificate’s validity.

string format: date-time

issued_at

Start of its validity.

string format: date-time

days_remaining

Whole days until expiry.

integer

issuer

The certificate’s issuer.

string

subject

The certificate’s subject.

string

serial_number

Serial number, hex.

string

sans

The names the certificate covers.

Array<string>

signature_algorithm

Signature algorithm.

string

key_size

Public key size in bits.

integer

is_wildcard

The certificate carries a wildcard name.

boolean

auto_renewal

Whether NSIN renews this certificate itself. True for managed-DNS domains and for external-DNS domains whose ssl_delegation is in place; false for an external-DNS domain that uploads its own.

boolean

has_private_key

NSIN holds the private key, so the certificate can be served.

boolean

can_manual_issue

Whether POST /domains/{domain}/ssl/issue would be accepted right now.

boolean

manual_issue_reason

Why manual issuance is unavailable, when can_manual_issue is false.

string

next_manual_issue_at

When the next manual issue is allowed (one per hour).

string format: date-time

last_issue_attempt_at

When a manual issue was last requested.

string format: date-time

failure_count

Consecutive failed orders for the domain’s own certificate. status flips to failed on the first one while retries continue; compare with max_retries to tell “still retrying” from “given up”. Absent when nothing has failed.

integer

max_retries

How many automatic retries a failing order gets. Absent when nothing has failed.

integer

next_retry_at

When the next automatic retry runs. Absent when none is scheduled.

string format: date-time

last_error

Why the last order failed, in the certificate authority’s words.

string

hostname

The name the reported certificate is installed under — usually the apex, but a domain may hold a certificate for one subdomain only.

string

covered_hostnames

Every name of this domain with an active certificate, sorted.

Array<string>

uncovered_hostnames

Proxied names with no certificate behind them, sorted. External-DNS domains only — for managed domains the same gaps arrive in coverage, with the retry schedule that applies when we can issue.

Array<string>

coverage

Proxied hostnames not yet on the certificate. Absent when coverage is complete.

Array<object>

A proxied hostname that the domain’s certificate does not cover yet.

object

hostname

string

status

pending — being issued; failed — the last attempt failed; missing — not requested yet.

string

Allowed values: pending failed missing

failure_count

Failed attempts so far for this name.

integer

max_retries

Automatic retries a failing name gets.

integer

next_retry_at

When the next automatic retry runs.

string format: date-time

last_error

The certificate authority’s own reason for the last failure.

string

trusted

Whether the served certificate chains to a public root. false means no browser will accept it — a private CA (for example a Cloudflare Origin CA certificate), a self-signed certificate, or an internal PKI. Absent when the bundle has not been evaluated, which is a different state from false and should not be shown as a failure.

boolean

trust_note

Why the certificate is flagged, phrased for the certificate’s owner. Can be present even when trusted is true — an otherwise genuine certificate missing its intermediate is reported here.

string

leaf_only

The bundle carries no intermediate certificate. Clients that do not already hold the issuer fail the handshake with “unable to get local issuer certificate”. Independent of trusted. Absent when the bundle has not been evaluated.

boolean

pinned

The certificate on display is one you chose, rather than whatever the domain would serve by default. See GET /domains/{domain}/ssl/certificates.

boolean

source

Where the certificate being served came from.

string

Allowed values: acme acme-staging uploaded

has_managed_cert

NSIN holds an unexpired certificate of its own for this domain — i.e. there is something to switch back to.

boolean

managed_requested

You have already asked NSIN to issue alongside your upload and the order is on its way.

boolean

can_request_managed

Whether POST /domains/{domain}/ssl/certificates/request would be accepted right now.

boolean

Example

{
  "status": "valid",
  "coverage": [
    {
      "status": "pending"
    }
  ],
  "source": "acme"
}

401

Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

Example invalidKey

{
  "error": "invalid API key"
}

404

No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

Example limited

{
  "error": "rate limit exceeded"
}