jwt_decode

Decode a JWT (JSON Web Token) and return the header and payload as JSON objects. The signature is never verified — any well-formed three-part token is accepted regardless of which secret was used or whether the token has expired.

Useful for inspecting token structure, extracting claims for debugging, or reading tokens received from third-party services when you do not have the signing secret.

Parameters

Parameter	Type	Required	Description
token	string	Yes	The JWT string to decode. Must have three dot-separated base64url-encoded parts (header.payload.signature).

Response

Field	Type	Description
header	object	The decoded JWT header as JSON.
payload	object	The decoded JWT payload as JSON.

Example

{
	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Result:

{
	"header": {
		"alg": "HS256",
		"typ": "JWT"
	},
	"payload": {
		"sub": "1234567890",
		"name": "John Doe",
		"iat": 1516239022
	}
}

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	The token field is missing or not a string.	protocol error (invalid_params)
jwt_malformed	The token does not have three dot-separated parts (header.payload.signature).	tool error (isError)
jwt_invalid_base64url	A token part is not valid base64url.	tool error (isError)
jwt_invalid_json	A token part does not decode to valid JSON.	tool error (isError)
internal_error	An unexpected server error.	protocol error (internal_error)

Notes

• Signature is ignored. jwt_decode is a base64url-split and JSON-parse operation — it never touches the signature. Use jwt_verify_hs256, jwt_verify_hs384, or jwt_verify_hs512 if you need to check the signature.
• Works on expired tokens. Because no claims are validated, jwt_decode is useful for inspecting tokens that can no longer be verified (e.g. tokens from old sessions stored in logs).
• Only HMAC-signed tokens are supported by the sign and verify tools. However, jwt_decode accepts any JWT regardless of the algorithm in the header — RSA and ECDSA tokens can be decoded for inspection.