SSL API

List active certificates expiring this year

query ExpiringSoon {
  sslCertificates(
    state: [active],
    expiresAtBefore: "2026-12-31T00:00:00Z",
    first: 50
  ) {
    nodes {
      id
      commonName
      expiresAt
      autoRenew
    }
    totalCount
  }
}

Renew a certificate

Reuses the existing certificate's CSR, contacts, validation method and other attributes — only the certificate id needs to be supplied.

mutation RenewSSLCertificate {
  renewSslCertificate(id: "1041") {
    workRequest {
      id
      type
      state
      createdAt
    }
  }
}

Sample response (renewal accepted and submitted):

{
  "data": {
    "renewSslCertificate": {
      "workRequest": {
        "id": "8821",
        "type": "RENEW_SSL_CERTIFICATE",
        "state": "submitted",
        "createdAt": "2026-05-28T09:42:11Z"
      }
    }
  }
}

Renewal is allowed when the certificate is not of an "external" type (i.e. managed through BrandShelter, not merely imported for tracking) and is currently in state active or expired. Otherwise the mutation returns:

{
  "errors": [
    {
      "message": "Certificate is not renewable",
      "extensions": { "code": "certificate_not_renewable" }
    }
  ],
  "data": { "renewSslCertificate": null }
}

Revoke a certificate

Allowed when the product type permits revocation (see SSLCertificateType.revocable) and the certificate is currently in state active.

mutation RevokeSSLCertificate {
  revokeSslCertificate(id: "1041") {
    sslCertificateId
    workRequestId
  }
}

Sample response:

{
  "data": {
    "revokeSslCertificate": {
      "sslCertificateId": "1041",
      "workRequestId": "8822"
    }
  }
}

Best Practices

• For ordered certificates, enrol in automatic renewal by passing autoRenew: true — the platform will then track expiry and trigger renewals on the client's behalf.
   

• For pure DV automation, prefer ACME over driving the GraphQL renew flow from a client. ACME is fully unattended once configured and integrates with standard tooling.
   

• Before attempting reissue or revoke, check SSLCertificateType.reissuable / .revocable for the product type — these flags drive the allowed actions and the matching error codes.
   

• For DigiCert and Sectigo products with vendor-mandated 199-day maximum lifetimes, no client action is required: the platform handles the auto-reissue cycle transparently, and clients see a normal 1-year renewal cadence.
   

• When polling work-request status, back off exponentially. Avoid tight polling loops against the GraphQL endpoint.
   

• Watch the certificate state for terminal failure states (order_failed, renewal_failed, reissue_failed) and surface them to operators promptly — they indicate a process that needs investigation.
   

• Log mutation errors with their extensions.code value (certificate_not_renewable, certificate_not_revocable, etc.) so support tooling can match on stable identifiers rather than message text.

Error Handling and Status Expectations

Certificate lifecycle states (SSLCertificateState enum):

• Stable / terminal: active, ordered, revoked, expired.

• In-flight (a work request is being processed): renewal_pending, reissue_pending, revocation_pending.

• Terminal failures: order_failed, renewal_failed, reissue_failed.

• Cancelled before completion: order_cancelled, renewal_cancelled, reissue_cancelled.

Common mutation error codes (in extensions.code):

• certificate_not_renewable — the certificate is of an "external" type, or is not currently in state active or expired.

• certificate_not_revocable — the certificate is not in state active, or the product type does not allow revocation.

Requesting an id that is not visible to the authenticated user, or that does not exist, returns a generic not-found / authorization error rather than disclosing whether the id exists.

For the full enum lists and field-level metadata, run a GraphQL introspection query against the live endpoint, or browse via a GraphQL client.