---
title: "Introspect Token"
method: POST
path: "/api/v1/tokens/introspect"
---

# Introspect Token

`POST /api/v1/tokens/introspect`

## Request

- Base URL: `https://api.skyfire.xyz`
- URL: `https://api.skyfire.xyz/api/v1/tokens/introspect`
- Auth: API key in header `skyfire-api-key`

Check whether a token is currently usable and get the remaining balance as a buyer or seller agent.

## Request body

- object
  - `token` string, required: The complete JWT string as issued to the buyer, not a `tokenId`. Can be of any token type: `kya`, `pay`, or `kya-pay`.

## Response `200`

Ok

- union
  - object
    - `expiresAt` number, required: Unix timestamp (seconds) after which the token expires; the token's `exp` claim.
    - `isValid` boolean, required: Whether the token passed introspection. `true` for up to 24 hours past `expiresAt` (settlement grace period).
    - `validationError` string: Present only when `isValid: false`. Human-readable, not a stable error code. Cases include: unparseable JWT, unknown token id, bad signature, past hold expiry, caller not a party to the token, malformed claims (`aud`/`sub`/`ssi`/`typ`), seller service inactive or unapproved, missing external seller or merchant account, wallet/address/network mismatch, balance-lookup failure. Unrecognized errors fall back to `Token is invalid or not found`.
  - object
    - `chargeableUntil` number, required: Unix timestamp (seconds) after which the token can no longer be charged.
    - `expiresAt` number, required: Unix timestamp (seconds) after which the token expires; the token's `exp` claim.
    - `isValid` boolean, required: Whether the token passed introspection. `true` until `chargeableUntil`.
    - `remainingBalance` string, required: Funds left on the token as a decimal string.
    - `validationError` string: Present only when `isValid: false`. Human-readable, not a stable error code. Cases include: unparseable JWT, unknown token id, bad signature, past hold expiry, caller not a party to the token, malformed claims (`aud`/`sub`/`ssi`/`typ`), seller service inactive or unapproved, missing external seller or merchant account, wallet/address/network mismatch, balance-lookup failure. Unrecognized errors fall back to `Token is invalid or not found`.

## Changes

- **2026-11-03** `22cbec9d7630`: 2 breaking, 1 info
  - request body became required
  - added `subschema #1: kya tokens, subschema #2: pay, kya-pay tokens` to the response body `oneOf` list for the response status `200`
  - removed `subschema #1: KYA Tokens, subschema #2: PAY, KYA-PAY Tokens` from the response body `oneOf` list for the response status `200`

[Operation history](https://skmtc.dev/skyfire/apis/skyfire-agent-and-token-apis/changes/api/v1/tokens/introspect/post.md)

---

[API](https://skmtc.dev/skyfire/apis/skyfire-agent-and-token-apis.md) - [All operations](https://skmtc.dev/skyfire/apis/skyfire-agent-and-token-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/skyfire/apis/skyfire-agent-and-token-apis/revisions/22cbec9d7630?raw)