Référence de l’API
L’API REST publique, opération par opération. Ces pages sont générées à partir du document OpenAPI de l’API : les champs, les exemples et les codes d’erreur sont donc ceux que l’API elle-même vérifie et renvoie.
- URL de base
https://ecdsa.com/api/v1- Document OpenAPI 3.1
- https://ecdsa.com/api/v1/openapi.json
Opérations
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).
Conventions
URL de base et versions
L’URL de chaque opération est formée de https://ecdsa.com/api suivie de son chemin, par exemple /v1/verify. La version fait partie du chemin : dans la v1, les réponses ne peuvent que s’enrichir de champs et de codes d’erreur. Ignorez donc les membres que vous ne connaissez pas et traitez un code inconnu d’après son statut HTTP.
Authentification
Aucune n’est nécessaire : chaque opération fonctionne de façon anonyme. Les clés d’API seront facultatives (envoyées sous la forme Authorization: Bearer … ou dans l’en-tête X-API-Key) et feront passer un appel de la limite par IP à la limite propre à la clé. Elles arriveront avec les comptes ecdsa.com. Un en-tête de clé mal formé est refusé avec unauthorized au lieu d’être ignoré.
Requêtes
Les corps des requêtes POST sont des objets JSON d’au plus 100 Ko, dont les tableaux et les objets sont imbriqués sur 64 niveaux au plus (les documents JSON contenus dans des champs de type chaîne comptent aussi). Les opérations GET prennent leur entrée dans le chemin.
En-têtes de réponse
Les en-têtes envoyés par l’API, et les cas où ils s’appliquent :
| En-tête | Contenu |
|---|---|
| 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"`. |
Erreurs
Un appel en échec renvoie un statut 4xx ou 5xx et cette enveloppe JSON ; le tableau des erreurs recense tous les codes.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| error | object | oui | |
| error.code | string | oui | 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 | oui | Human-readable explanation (English). |
| error.requestId | string | non | The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1. |
| error.detail | object | non | Structured context for the error, such as the offending field; omitted when there is none.
|
| error.docs | string | non | Where the error codes are explained. Sent since v1.1.
|
Limites de requêtes
60 requêtes par minute et par IP sur l’ensemble de l’API, plus 10 par minute pour les opérations qui analysent un domaine. Une réponse 429 porte Retry-After.
Clés privées
N’en envoyez jamais. Une requête qui contient des données de clé privée, où que ce soit (un bloc PEM PRIVATE KEY, une clé OpenSSH, SSH2 ou PuTTY, une JWK avec « d »), est refusée avec private_key_rejected avant tout autre traitement.