Skip to API content
Birdor API v1

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.

POST/v1/run/jwt/decode

Access 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

FieldDescription
AuthorizationstringOptionalBearer API key with tools.run; alternatively X-API-Key. One of the credentials is required.
X-API-KeystringOptionalAlternative to Authorization; never send both.
X-Birdor-Workspace-IDstringOptionalRequired with the site session; optional and matching with an API key.
X-Birdor-Project-IDstringOptionalOptional owned project; a project-bound key cannot select another project.

Request body

Send JSON with Content-Type: application/json.

FieldDescription
tokenstringRequiredCompact JWS/JWT (header.payload.signature), at most 12000 characters; a leading "Bearer " is ignored. Decoded in memory only; the signature is NOT verified.
atstringOptionalRFC 3339 instant to evaluate exp/nbf against; default request time.
clockSkewSecondsintegerOptionalLeeway applied to exp and nbf, 0–3600 seconds; default 0.

Request example

1. Set the base URL

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
HTTP 200
{
  "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
HTTP 400
{
  "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
HTTP 401
{
  "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
HTTP 403
{
  "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
HTTP 405
{
  "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
HTTP 408
{
  "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
HTTP 413
{
  "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
HTTP 415
{
  "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
HTTP 429
{
  "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
HTTP 500
{
  "ok": false,
  "code": "OPERATION_FAILED",
  "message": "Operation failed",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
503Authentication/metering dependency unavailable
HTTP 503
{
  "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
HTTP 422
{
  "ok": false,
  "code": "MALFORMED_JWT",
  "message": "Not three dot-separated segments",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
Error handling

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.