> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /jwt-decoder

> Decode and inspect JWT tokens. Returns header, payload, and expiration metadata without verification.

## Endpoint

```
POST https://api.bunny.build/api/v1/jwt-decoder
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Decode any JSON Web Token (JWT) and inspect its header, payload claims, and expiration metadata. This endpoint does not verify the signature; it decodes the token structure for debugging, logging, and display purposes.

## Use cases

* Debug token claims during development and integration testing
* Display user metadata from a JWT in an admin panel
* Log token details for audit trails without storing raw tokens
* Inspect third-party tokens to understand their structure

## Details

Decodes standard three-part JWTs (header.payload.signature). Signature verification is not performed. The raw signature string is returned alongside the decoded header and payload. Human-readable timestamps and token status flags are derived from standard claims and returned in a `meta` object.

## Request body

| Field   | Type   | Required | Description          |
| ------- | ------ | -------- | -------------------- |
| `token` | string | Yes      | JWT string to decode |

### Example

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
```

## Response

### 200 OK

| Field       | Type   | Description                                                       |
| ----------- | ------ | ----------------------------------------------------------------- |
| `header`    | object | Decoded JWT header claims (e.g. `alg`, `typ`)                     |
| `payload`   | object | Decoded JWT payload claims                                        |
| `signature` | string | Raw base64url-encoded signature segment (third part of the token) |
| `meta`      | object | Derived metadata — see fields below                               |

**meta**

| Field           | Type            | Description                                                           |
| --------------- | --------------- | --------------------------------------------------------------------- |
| `algorithm`     | string \| null  | Signing algorithm from `header.alg` (e.g. `"HS256"`)                  |
| `type`          | string \| null  | Token type from `header.typ` (e.g. `"JWT"`)                           |
| `issued_at`     | string \| null  | ISO 8601 timestamp derived from `iat` claim                           |
| `expires_at`    | string \| null  | ISO 8601 timestamp derived from `exp` claim                           |
| `not_before`    | string \| null  | ISO 8601 timestamp derived from `nbf` claim                           |
| `issuer`        | string \| null  | Value of the `iss` claim                                              |
| `subject`       | string \| null  | Value of the `sub` claim                                              |
| `audience`      | string \| null  | Value of the `aud` claim                                              |
| `expired`       | boolean \| null | Whether the token is currently expired (null if no `exp` claim)       |
| `not_yet_valid` | boolean \| null | Whether the token is not yet valid per `nbf` (null if no `nbf` claim) |

**Example**

```json theme={null}
{
  "header": { "alg": "HS256", "typ": "JWT" },
  "payload": {
    "sub": "1234567890",
    "name": "John Doe",
    "iat": 1516239022,
    "exp": 1893456000
  },
  "signature": "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "meta": {
    "algorithm": "HS256",
    "type": "JWT",
    "issued_at": "2018-01-18T01:30:22.000Z",
    "expires_at": "2029-12-31T00:00:00.000Z",
    "not_before": null,
    "issuer": null,
    "subject": "1234567890",
    "audience": null,
    "expired": false,
    "not_yet_valid": null
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Invalid JWT format"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/jwt-decoder \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'
```