JWT

Decode a JWT (no signature check)

POSThttps://ecdsa.com/api/v1/jwt/decode

Decodes a compact JWS token: header, payload, enriched exp/iat/nbf time claims and a classification of the algorithm. The signature is NOT verified — the response carries verified: false explicitly. Use /v1/jwt/verify to check ES* signatures.

API key: Optional; a key needs the scope api
Quota cost with a key: 1 unit per call
Rate limit: 60 requests/min per IP

Request

JSON body: JwtDecodeRequest

Field	Type	Required	Description
token	string	yes	Compact JWS token. A leading "Bearer " and whitespace are stripped.

Responses

200The decoded token (signature not verified).

Field	Type	Required	Description
header	object	yes	any member names
payload	object	yes	any member names
signaturePresent	boolean	yes
signatureBytes	integer	yes	at least 0
timeClaims	object	yes
timeClaims.exp	TimeClaim	yes
timeClaims.iat	TimeClaim	yes
timeClaims.nbf	TimeClaim	yes
timeClaims.status	object \| null	yes	null when the token carries no usable exp or nbf.
timeClaims.status.kind	string	yes	one of "expired", "not-yet-valid", or "valid"
timeClaims.status.detail	string	yes
algInfo	AlgInfo	yes
verified	boolean	yes	Always false — this operation never verifies. always false
note	string	yes

Headers: X-Request-Id · X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset · X-Quota-Limit · X-Quota-Remaining · X-Quota-Reset

Status	Meaning	Codes
400	Bad request. Input limits: a request body of at most 100 KB (a larger one is answered with 413) and arrays and objects nested at most 64 levels deep, JSON documents inside string fields included.	invalid_json missing_field invalid_input private_key_rejected
401	Unauthorized.	unauthorized
403	Forbidden.	forbidden_scope
404	Not found.	not_found
405	Method not allowed.	method_not_allowed
413	Payload too large.	payload_too_large
429	Too many requests.	rate_limited quota_exceeded
500	Internal server error.	internal_error
503	Service unavailable.	service_unavailable
504	Gateway timeout.	timeout

Every error answer carries the JSON envelope; the error table says what each code means and what to do.

Example

An ES256 token

curl

curl -sS 'https://ecdsa.com/api/v1/jwt/decode' \
  -H 'content-type: application/json' \
  -d '{
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNvcHBlci1leGFtcGxlLTEifQ.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLmNvbSIsInN1YiI6InVzZXJfNDIiLCJhdWQiOiJlY2RzYSIsImlhdCI6MTc4NzE0MDgwMCwiZXhwIjo0MDcwOTA4ODAwfQ.fQpTQxkahGRlZp-U71-xNk68mpZH23dhn9QoysMLmZfBx_e-vd9sCgh7sJ4eXu0-WbQSNqzmVPyUKErCJx4DHw"
}'

JavaScript (fetch)

const response = await fetch("https://ecdsa.com/api/v1/jwt/decode", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNvcHBlci1leGFtcGxlLTEifQ.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLmNvbSIsInN1YiI6InVzZXJfNDIiLCJhdWQiOiJlY2RzYSIsImlhdCI6MTc4NzE0MDgwMCwiZXhwIjo0MDcwOTA4ODAwfQ.fQpTQxkahGRlZp-U71-xNk68mpZH23dhn9QoysMLmZfBx_e-vd9sCgh7sJ4eXu0-WbQSNqzmVPyUKErCJx4DHw"
  }),
});
console.log(response.status, await response.json());

Python (httpx)

import httpx

response = httpx.post(
    "https://ecdsa.com/api/v1/jwt/decode",
    json={
        "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNvcHBlci1leGFtcGxlLTEifQ.eyJpc3MiOiJodHRwczovL2lzc3Vlci5leGFtcGxlLmNvbSIsInN1YiI6InVzZXJfNDIiLCJhdWQiOiJlY2RzYSIsImlhdCI6MTc4NzE0MDgwMCwiZXhwIjo0MDcwOTA4ODAwfQ.fQpTQxkahGRlZp-U71-xNk68mpZH23dhn9QoysMLmZfBx_e-vd9sCgh7sJ4eXu0-WbQSNqzmVPyUKErCJx4DHw",
    },
    timeout=30.0,
)
print(response.status_code, response.json())

Response 200

{
  "header": {
    "alg": "ES256",
    "typ": "JWT",
    "kid": "copper-example-1"
  },
  "payload": {
    "iss": "https://issuer.example.com",
    "sub": "user_42",
    "aud": "ecdsa",
    "iat": 1787140800,
    "exp": 4070908800
  },
  "signaturePresent": true,
  "signatureBytes": 64,
  "timeClaims": {
    "exp": {
      "value": 4070908800,
      "utc": "2099-01-01 00:00:00 UTC",
      "relative": "in 72 years"
    },
    "iat": {
      "value": 1787140800,
      "utc": "2026-08-19 12:00:00 UTC",
      "relative": "61 days ago"
    },
    "nbf": null,
    "status": {
      "kind": "valid",
      "detail": "valid until 2099-01-01 00:00:00 UTC (in 72 years)"
    }
  },
  "algInfo": {
    "alg": "ES256",
    "kind": "ecdsa",
    "curve": "P-256",
    "hash": "SHA-256",
    "signatureBytes": 64,
    "verifiableHere": true,
    "summary": "ES256 is ECDSA on P-256 with SHA-256; the JWS signature is raw r‖s (64 bytes). POST /api/v1/jwt/verify can check it."
  },
  "verified": false,
  "note": "This endpoint decodes the token without checking the signature. Use POST /api/v1/jwt/verify (ES256/ES384/ES512) to verify it against a public key."
}

The API’s answer to this example, produced for this page on October 20, 2026; relative times and day counts in it refer to that day.

Error codes

Code	Status	Meaning
invalid_json	400	The body is not valid JSON or not a JSON object; or the input nests arrays and objects more than 64 levels deep (JSON documents inside string fields count too), or is too complex to inspect for private keys.
missing_field	400	A required field is absent or empty.
invalid_input	400	A field could not be parsed — the message explains exactly why.
private_key_rejected	400	The request contains private-key material (a PEM PRIVATE KEY block, an OpenSSH, SSH2 or PuTTY private key, or a JWK with "d"). Never send private keys anywhere.
unauthorized	401	The Authorization or X-API-Key header is malformed, the API key is not valid (wrong checksum, unknown, revoked or expired), or the operation needs a key.
forbidden_scope	403	The API key is valid but lacks a scope this operation requires; the message names it.
not_found	404	No operation exists at this path.
method_not_allowed	405	The path exists but does not accept this HTTP method; see the Allow header.
payload_too_large	413	The body exceeds 100 KB.
rate_limited	429	Too many requests — see Retry-After.
quota_exceeded	429	A daily or monthly quota of the API key's account is used up. X-Quota-Reset (and Retry-After) say when it starts over; retrying earlier cannot succeed.
internal_error	500	Unexpected server error.
service_unavailable	503	API keys cannot be verified right now (the key store is unreachable); retry shortly.
timeout	504	The operation did not finish within its time budget.

Schemas

TimeClaim

null when the claim is absent; {error} when it is malformed.

Field	Type	Required	Description
Shape 1value	number	yes	Seconds since the epoch.
Shape 1utc	string	yes
Shape 1relative	string	yes	For example "in 72 years" or "3 minutes ago".
Shape 2error	string	yes

AlgInfo

Classification of the header's alg value.

Field	Type	Required	Description
alg	string \| null	yes
kind	string	yes	one of "ecdsa", "none", "hmac", "rsa", "eddsa", "missing", or "unknown"
curve	string	no	one of "P-256", "P-384", "P-521", or "secp256k1"
hash	string	no	one of "SHA-256", "SHA-384", or "SHA-512"
signatureBytes	integer	no	at least 0
verifiableHere	boolean	yes	Whether POST /v1/jwt/verify can check this token.
summary	string	yes

Error

The error envelope of every non-2xx response.

Field	Type	Required	Description
error	object	yes
error.code	string	yes	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	yes	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. any member names
error.docs	string	no	Where the error codes are explained. Sent since v1.1. format uri

All operations are listed in the API reference.