API reference · v1
Decode a JWT
Decode a compact JWT without verifying its signature: header, payload, algorithm family, and time semantics (iat/nbf/exp as instants, validity status with optional clock skew, seconds until expiry and token age). warnings flag alg none, a missing signature, no exp, lifetimes over 30 days, iat in the future, crit headers, non-numeric time claims and claim names that look sensitive. The token is a credential: it is processed in memory only and never stored or logged. verified is always false; use a signature check before trusting any claim. Requires a credential with tools.run; every accepted call consumes one monthly unit, including business 4xx/5xx. Sensitive: request bodies are processed in memory only and are never stored, logged or hashed into usage records.
/v1/run/jwt/decodeAccess requirements
Health, metadata, changelog and waitlist routes are public. Catalog reads (GET /v1/tools, /v1/tools/{id}, /v1/colors/*) and POST /v1/tools/query require a tools.read credential; POST /v1/run/* requires tools.run. There is no anonymous access to these routes: send an API key (Bearer OR X-API-Key) from your server, or use the HttpOnly main-site session plus workspace selection and same-origin Origin. Never combine credentials. Every admitted call is metered. Ingress and workspace/actor minute/month limits are separate; waitlist has its own policy.
Implemented interfaces and development screens do not imply public production availability, paid access or a completed payment integration. Confirm access with Birdor before connecting an application. No paid Pro service, activation or cross-device sync is currently delivered. We are validating one repeatable task before building a paid offer.
Parameters
| Field | Description |
|---|---|
AuthorizationstringOptional | Bearer API key with tools.run; alternatively X-API-Key. One of the credentials is required. |
X-API-KeystringOptional | Alternative to Authorization; never send both. |
X-Birdor-Workspace-IDstringOptional | Required with the site session; optional and matching with an API key. |
X-Birdor-Project-IDstringOptional | Optional owned project; a project-bound key cannot select another project. |
Request body
Send JSON with Content-Type: application/json.
| Field | Description |
|---|---|
tokenstringRequired | Compact JWS/JWT (header.payload.signature), at most 12000 characters; a leading "Bearer " is ignored. Decoded in memory only; the signature is NOT verified. |
atstringOptional | RFC 3339 instant to evaluate exp/nbf against; default request time. |
clockSkewSecondsintegerOptional | Leeway applied to exp and nbf, 0–3600 seconds; default 0. |
Request example
curl --request POST "$BIRDOR_API_BASE_URL/v1/run/jwt/decode" \
--header "Accept: application/json" \
--header "Authorization: Bearer $BIRDOR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJCaXJkb3IiLCJzdWIiOiJkZXZlbG9wZXIiLCJpYXQiOjE2MDAwMDAwMDAsIm5iZiI6MTYwMDAwMDAwMCwiZXhwIjoyMDUxMjIyNDAwfQ.ayqPfC0gbylOMJCNh1jCyv84SEF4YwQuro459lHO9EQ",
"at": "2026-10-11T00:00:00Z"
}'Examples are copied only; this page does not send API requests.
Responses
Illustrative response. Values vary by environment and time.
200Success
{
"ok": true,
"data": {
"verified": false,
"header": {
"alg": "HS256",
"typ": "JWT"
},
"payload": {
"iss": "Birdor",
"sub": "developer",
"iat": 1600000000,
"nbf": 1600000000,
"exp": 2051222400
},
"signature": {
"present": true,
"bytes": 32
},
"algorithm": {
"name": "HS256",
"family": "HMAC"
},
"time": {
"evaluatedAt": "2026-10-11T00:00:00.000Z",
"status": "valid",
"issuedAt": {
"unix": 1600000000,
"iso": "2020-09-13T12:26:40.000Z"
},
"notBefore": {
"unix": 1600000000,
"iso": "2020-09-13T12:26:40.000Z"
},
"expiresAt": {
"unix": 2051222400,
"iso": "2035-01-01T00:00:00.000Z"
},
"expiresInSeconds": 259545600,
"ageSeconds": 191676800
},
"warnings": [
{
"code": "LONG_LIVED",
"message": "exp is more than 30 days after iat."
}
]
},
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}400Invalid JSON, schema validation failure (field paths/codes only, never input values) or ambiguous credentials
{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}401Missing, expired, rotated, revoked or invalid credential; there is no anonymous access
{
"ok": false,
"code": "UNAUTHENTICATED",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}403Key lacks tools.run, or workspace/project/member policy or site Origin denied
{
"ok": false,
"code": "FORBIDDEN",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}405Only POST is supported; rejected before admission
{
"ok": false,
"code": "METHOD_NOT_ALLOWED",
"message": "Method not allowed",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}408Body read exceeds five seconds; before admission
{
"ok": false,
"code": "REQUEST_TIMEOUT",
"message": "Request body timeout or aborted",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}413Body exceeds 16384 bytes; before admission
{
"ok": false,
"code": "PAYLOAD_TOO_LARGE",
"message": "Request body too large",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}415Content-Type must be application/json; before admission
{
"ok": false,
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "JSON content type required",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}429Ingress, workspace/actor minute or monthly quota exceeded; inspect code and Retry-After
{
"ok": false,
"code": "QUOTA_EXCEEDED",
"message": "API request limit exceeded",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}500Unexpected operation failure; details are never echoed
{
"ok": false,
"code": "OPERATION_FAILED",
"message": "Operation failed",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}503Authentication/metering dependency unavailable
{
"ok": false,
"code": "API_GATEWAY_UNAVAILABLE",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}422MALFORMED_JWT: Not three dot-separated segments; JWE_NOT_SUPPORTED: Five segments: an encrypted JWE cannot be decoded without the key; INVALID_JWT_HEADER: Header is not a base64url-encoded JSON object; INVALID_JWT_PAYLOAD: Payload is not a base64url-encoded JSON object; INVALID_JWT_SIGNATURE: Signature segment is not base64url
{
"ok": false,
"code": "MALFORMED_JWT",
"message": "Not three dot-separated segments",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}Example response fields
Fields shown in this example; optional fields can be omitted. Array rows describe the first example element.
- okboolean
- Application success flag.
- dataobject
- Endpoint-specific result.
- data.verifiedboolean
- Endpoint-specific example value.
- data.headerobject
- Endpoint-specific example value.
- data.header.algstring
- Endpoint-specific example value.
- data.header.typstring
- Endpoint-specific example value.
- data.payloadobject
- Endpoint-specific example value.
- data.payload.issstring
- Endpoint-specific example value.
- data.payload.substring
- Endpoint-specific example value.
- data.payload.iatnumber
- Endpoint-specific example value.
- data.payload.nbfnumber
- Endpoint-specific example value.
- data.payload.expnumber
- Endpoint-specific example value.
- data.signatureobject
- Endpoint-specific example value.
- data.signature.presentboolean
- Endpoint-specific example value.
- data.signature.bytesnumber
- Endpoint-specific example value.
- data.algorithmobject
- HMAC hash algorithm.
- data.algorithm.namestring
- Name or token identifier.
- data.algorithm.familystring
- Endpoint-specific example value.
- data.timeobject
- Endpoint-specific example value.
- data.time.evaluatedAtstring
- Endpoint-specific example value.
- data.time.statusstring
- Operation result.
- data.time.issuedAtobject
- Endpoint-specific example value.
- data.time.issuedAt.unixnumber
- Endpoint-specific example value.
- data.time.issuedAt.isostring
- Endpoint-specific example value.
- data.time.notBeforeobject
- Endpoint-specific example value.
- data.time.notBefore.unixnumber
- Endpoint-specific example value.
- data.time.notBefore.isostring
- Endpoint-specific example value.
- data.time.expiresAtobject
- Endpoint-specific example value.
- data.time.expiresAt.unixnumber
- Endpoint-specific example value.
- data.time.expiresAt.isostring
- Endpoint-specific example value.
- data.time.expiresInSecondsnumber
- Endpoint-specific example value.
- data.time.ageSecondsnumber
- Endpoint-specific example value.
- data.warningsarray
- Endpoint-specific example value.
- data.warnings[].codestring
- Application error code.
- data.warnings[].messagestring
- Error message.
- request_idstring
- Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
- timestampstring
- Response creation timestamp.