Referencia de la API
La API REST pública, operación por operación. Las páginas se generan a partir del documento OpenAPI de la API, así que los campos, los ejemplos y los códigos de error son los mismos que la propia API comprueba y envía.
- URL base
https://ecdsa.com/api/v1- Documento OpenAPI 3.1
- https://ecdsa.com/api/v1/openapi.json
Operaciones
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).
Convenciones
URL base y versiones
Cada operación tiene su ruta bajo https://ecdsa.com/api, por ejemplo /v1/verify. La versión forma parte de la ruta: dentro de la v1, las respuestas solo pueden ganar campos y códigos de error, así que ignora los miembros que no conozcas y trata un código desconocido según su estado HTTP.
Autenticación
No hace falta: todas las operaciones funcionan de forma anónima. Las claves de API serán opcionales —se enviarán como Authorization: Bearer … o en el encabezado X-API-Key— y harán que una llamada pase del límite por IP al límite propio de la clave. Llegarán con las cuentas de ecdsa.com. Un encabezado de clave mal formado se rechaza con unauthorized en lugar de ignorarse.
Solicitudes
Los cuerpos de las solicitudes POST son objetos JSON de 100 KB como máximo, con arrays y objetos anidados hasta 64 niveles de profundidad como máximo (también cuentan los documentos JSON dentro de campos de tipo cadena). Las operaciones GET toman su entrada de la ruta.
Encabezados de respuesta
Los encabezados que envía la API y dónde se aplican:
| Encabezado | Qué contiene |
|---|---|
| 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"`. |
Errores
Una llamada fallida responde con un estado 4xx o 5xx y este sobre JSON; la tabla de errores enumera todos los códigos.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| error | object | sí | |
| error.code | string | sí | 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 | sí | Human-readable explanation (English). |
| error.requestId | string | no | The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1. |
| error.detail | object | no | Structured context for the error, such as the offending field; omitted when there is none.
|
| error.docs | string | no | Where the error codes are explained. Sent since v1.1.
|
Límites de frecuencia
60 solicitudes por minuto por IP en toda la API, más 10 por minuto para las operaciones que escanean un dominio. Una respuesta 429 incluye Retry-After.
Claves privadas
Nunca envíes una. Una solicitud que contenga material de clave privada en cualquier parte —un bloque PEM PRIVATE KEY, una clave de OpenSSH, SSH2 o PuTTY, una JWK con «d»— se rechaza con private_key_rejected antes de que ocurra nada más.