# JWT Verification Service (jwt.lol) Verify JSON Web Tokens (JWTs) by providing keys/secrets directly in your request. Supported Algorithms: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512. *Note: Asymmetric algorithms (RS*, ES*, PS*) require using the `POST /` JSON body method.* ## Endpoints ### `GET /` (Usage Information) Returns this usage information as plain text **if no verification parameters are provided**. ### `GET /` (Verification - Symmetric Keys Only) Verifies the provided JWT using a secret supplied via query parameters or headers. Choose **one** method for providing the secret and algorithm. **Method 1: Query Parameters** - URL Parameters: - `token`: The JWT string (required). - `secret`: The shared secret string (required). - `algorithm`: The algorithm used (e.g., "HS256", "HS384", "HS512") (required). - **Example (HS256):** ```bash # Note: URL encode token and secret if they contain special characters curl -G https://jwt.lol/ --data-urlencode "token=eyJ..." \ --data-urlencode "secret=your-secret" \ --data-urlencode "algorithm=HS256" ``` **Method 2: Headers** - URL Parameter: - `token`: The JWT string (required). - Headers: - `X-JWT-Secret`: Your shared secret string (required). - `X-JWT-Algorithm`: e.g., `HS256`, `HS384`, `HS512` (Optional, defaults to `HS256` if omitted. Must match algorithm in Basic Auth if used). - **Example (HS256 default):** ```bash curl -G https://jwt.lol/ --data-urlencode "token=eyJ..." \ -H "X-JWT-Secret: your-secret" ``` - **Example (HS384 explicit):** ```bash curl -G https://jwt.lol/ --data-urlencode "token=eyJ..." \ -H "X-JWT-Secret: your-secret" -H "X-JWT-Algorithm: HS384" ``` **Method 3: Basic Authentication** - URL Parameter: - `token`: The JWT string (required). - Header: `Authorization: Basic ` - The algorithm part *must* be a supported symmetric algorithm (HS256, HS384, HS512). - **Example (HS256):** ```bash # Basic base64(HS256:your-secret) -> SEMyNTY6eW91ci1zZWNyZXQ= curl -G https://jwt.lol/ --data-urlencode "token=eyJ..." \ -H "Authorization: Basic SEMyNTY6eW91ci1zZWNyZXQ=" ``` **Important:** You cannot mix secret sources (e.g., provide both `secret` query parameter and `X-JWT-Secret` header). If providing algorithm via multiple sources (e.g., query parameter and Basic Auth), they must match. ### `POST /` (Verification - All Key Types) Verifies the provided JWT using keys/secrets supplied directly in the request body or headers. Choose **one** of the following input methods: **Method 1: JSON Body (Supports Symmetric and Asymmetric Keys)** - `Content-Type: application/json` - Body: JSON object containing: - `token`: The JWT string (required). - `algorithm`: The algorithm used (e.g., "HS256", "RS256") (required). - *Either* `secret`: The shared secret string (for HS* algorithms). - *Or* `publicKey`: The PEM-encoded public key string (for RS*, ES*, PS* algorithms). - **Example (HS256):** ```bash curl https://jwt.lol/ -H "Content-Type: application/json" \ -d '{ "token": "eyJ...", "secret": "your-secret", "algorithm": "HS256" }' ``` - **Example (RS256):** ```bash curl https://jwt.lol/ -H "Content-Type: application/json" \ -d '{ "token": "eyJ...", "publicKey": "-----BEGIN...", "algorithm": "RS256" }' ``` **Method 2: Headers (Symmetric Keys Only - HS*)** - `Content-Type: text/plain` (or `application/jwt`) - Body: The raw JWT string. - Headers: - `X-JWT-Secret`: Your shared secret string (required). - `X-JWT-Algorithm`: e.g., `HS256`, `HS384`, `HS512` (Optional, defaults to `HS256` if omitted. Must match algorithm in Basic Auth if used). - **Example (HS256):** ```bash curl https://jwt.lol/ -H "Content-Type: text/plain" \ -H "X-JWT-Secret: your-secret" -H "X-JWT-Algorithm: HS256" \ --data "eyJ..." ``` **Method 3: Basic Authentication (Symmetric Keys Only - HS*)** - `Content-Type: text/plain` (or `application/jwt`) - Body: The raw JWT string. - Header: `Authorization: Basic ` - The algorithm part *must* be a supported symmetric algorithm (HS256, HS384, HS512). - **Example (HS256):** ```bash # Basic base64(HS256:your-secret) -> SEMyNTY6eW91ci1zZWNyZXQ= curl https://jwt.lol/ -H "Content-Type: text/plain" \ -H "Authorization: Basic SEMyNTY6eW91ci1zZWNyZXQ=" \ --data "eyJ..." ``` ## Responses (Verification Requests - `GET` or `POST`) - **Success (200 OK):** Returns the verified JWT payload as JSON. - **Failure (4xx/5xx):** Returns a JSON error object: `{ "error": "error_code", "error_description": "..." }` ## Common Error Responses The service returns standard HTTP status codes and a JSON body with `error` and `error_description` on failure. | Status | Error Code | Description (Context: G=GET Verify, P=POST Verify) | | :----- | :------------------------- | :-------------------------------------------------------------------------- | | `400` | `missing_token` | Token missing (G: query param; P: body/field). | | `400` | `missing_key` | Required secret/key missing (G: query/header/auth; P: JSON/header/auth). | | `400` | `missing_public_key` | Required `publicKey` missing (P: JSON). *Now covered by `missing_key`* | | `400` | `missing_algorithm` | Required `algorithm` missing (G: query/header/auth; P: JSON/header/auth). | | `400` | `invalid_json` | Malformed JSON body (P: JSON). | | `400` | `invalid_request` | Invalid input combination (e.g., secret+publicKey, conflicting sources) (G, P). | | `400` | `invalid_auth_header` | Invalid Basic Auth header format (G, P: Basic Auth). | | `400` | `invalid_auth_credentials` | Invalid Basic Auth credentials format (expected "algorithm:secret") (G, P: Basic Auth). | | `400` | `invalid_auth_algorithm` | Asymmetric/unsupported algorithm used with Basic Auth (G, P: Basic Auth). | | `400` | `alg_not_supported` | Specified algorithm is not supported by the underlying library (G, P). | | `400` | `invalid_public_key` | Failed to parse public key (ensure PEM SPKI format) (P: JSON). | | `400` | `invalid_key_for_alg` | Key type incompatible with algorithm (e.g., secret for RS*) (P: JSON). | | `401` | `token_expired` | Token has expired (`exp` claim) (G, P). | | `401` | `signature_invalid` | Token signature verification failed (G, P). | | `401` | `token_malformed` | Token is malformed or JWS structure is invalid (G, P). | | `401` | `claim_invalid` | Generic token claim validation failure (e.g., `nbf`, `iat`, `aud`, `iss`) (G, P). | | `405` | `method_not_allowed` | Used unsupported HTTP method on `/`. | | `415` | `unsupported_media_type` | Unsupported `Content-Type` for POST (P). | | `500` | `internal_server_error` | Unexpected server error during processing (G, P). | | `500` | `body_read_error` | Failed to read request body (P). | | `500` | `key_preparation_error` | Internal error preparing key from input (G, P). | | `404` | `not_found` | Requested path does not exist. | --- **Disclaimer: JWT Verification Service (jwt.lol)** This free service helps verify JWTs for devices that can't do it themselves. **Important Risks:** * **Key Exposure:** When using this service, you send your secret keys or public keys (via POST JSON) to this service. Sending keys to *any* external service is less secure than verifying locally. Using GET requests exposes secrets in URLs, which might be logged by proxies or servers. **POST is generally preferred over GET for sending secrets.** * **Reliability:** This is a free service with no guarantee of uptime or performance. * **Security:** The service could be targeted by attacks. **Do NOT use this service for sensitive production systems or data.** Keys and verification should ideally happen within your own secure environment. By using this service, you accept these risks. Use is entirely at your own risk. --- *Disclaimer: This tool was generated by AI via Aider and Gemini 2.5 Pro.*