API-Referenz
Die öffentliche REST-API, Operation für Operation. Die Seiten werden aus dem OpenAPI-Dokument der API erzeugt – Felder, Beispiele und Fehlercodes sind also genau die, die die API selbst prüft und sendet.
- Basis-URL
https://ecdsa.com/api/v1- OpenAPI-3.1-Dokument
- https://ecdsa.com/api/v1/openapi.json
Operationen
Signatures
ECDSA signature verification and DER ⇄ raw r‖s conversion.
JWT
Decoding JSON Web Tokens and verifying ES256/ES384/ES512 signatures.
Certificates
X.509 certificate and chain decoding with assessments.
Domain health
TLS signature-health grades of public domains. These operations connect to the domain.
Webhooks
Webhook endpoints of the API key's account and test deliveries. These operations need an API key with the webhooks scope; deliveries are signed with ECDSA P-256 (ES256).
Konventionen
Basis-URL und Versionen
Jede Operation liegt unter https://ecdsa.com/api, gefolgt von ihrem Pfad, etwa /v1/verify. Die Version ist Teil des Pfads: Innerhalb von v1 kommen in Antworten immer nur Felder und Fehlercodes hinzu – ignoriere also Felder, die du nicht kennst, und behandle einen unbekannten Code nach seinem HTTP-Status.
Authentifizierung
Nicht nötig: Jede Operation funktioniert anonym. API-Schlüssel werden optional sein – gesendet als Authorization: Bearer … oder im Header X-API-Key –, und für einen Aufruf mit Schlüssel gilt dann statt des Limits pro IP das eigene Limit des Schlüssels. Die Schlüssel kommen mit den Konten auf ecdsa.com. Ein fehlerhaft formatierter Schlüssel-Header wird mit unauthorized abgewiesen statt ignoriert.
Anfragen
POST-Bodys sind JSON-Objekte mit höchstens 100 KB, in denen Arrays und Objekte höchstens 64 Ebenen tief verschachtelt sind (JSON-Dokumente in String-Feldern zählen mit). GET-Operationen beziehen ihre Eingabe aus dem Pfad.
Antwort-Header
Die Header, die die API sendet, und wo sie vorkommen:
| Header | Was er enthält |
|---|---|
| X-Request-Id | Identifier of this request, also quoted in every error body. A caller's own X-Request-Id (1–128 characters of A–Z, a–z, 0–9, '.', '_', ':' and '-') is echoed unless it contains an API key; otherwise one is generated. |
| X-RateLimit-Limit | Requests allowed per window by the limit reported on this response. |
| X-RateLimit-Remaining | Requests left in the current window. |
| X-RateLimit-Reset | Unix time (seconds) at which the current window ends. |
| X-Quota-Limit | Calls made with an API key only: the size of the account's quota that runs out first for this operation — daily or monthly quota units, or daily domain scans. |
| X-Quota-Remaining | Calls made with an API key only: what is left of that quota after this call. |
| X-Quota-Reset | Calls made with an API key only: Unix time (seconds) at which that quota starts over. |
| Retry-After | Seconds to wait before retrying; for quota_exceeded, until the quota starts over. |
| Allow | The methods this path accepts. |
| WWW-Authenticate | The bearer challenge (RFC 6750), e.g. `Bearer realm="ecdsa.com", error="invalid_token"`. |
Fehler
Ein fehlgeschlagener Aufruf antwortet mit einem 4xx- oder 5xx-Status und diesem JSON-Fehlerobjekt; die Fehlertabelle listet alle Codes auf.
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| error | object | ja | |
| error.code | string | ja | Machine-readable error code. Each response lists the codes it can carry; new codes may be added within v1, so treat an unknown code by its HTTP status. |
| error.message | string | ja | Human-readable explanation (English). |
| error.requestId | string | nein | The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1. |
| error.detail | object | nein | Structured context for the error, such as the offending field; omitted when there is none.
|
| error.docs | string | nein | Where the error codes are explained. Sent since v1.1.
|
Rate Limits
60 Anfragen pro Minute und IP für die gesamte API, dazu 10 pro Minute für die Operationen, die eine Domain scannen. Eine 429-Antwort enthält Retry-After.
Private Schlüssel
Sende nie einen. Eine Anfrage, die irgendwo Material eines privaten Schlüssels enthält – einen PEM-Block „PRIVATE KEY“, einen OpenSSH-, SSH2- oder PuTTY-Schlüssel, einen JWK mit „d“ –, wird mit private_key_rejected abgewiesen, bevor irgendetwas anderes passiert.