Skyfire tokens are standard signed JWTs. Your service must verify the token signature and validate required claims before authorizing access or fulfilling payment.

Token Format & Signature

Tokens are standard Signed JWTs
Signing algorithm: ES256
Header includes:
- alg: ES256
- kid: JWK key ID
- typ: One of:
  - kya+jwt
  - pay+jwt
  - kya-pay+jwt

Public Keys (JWKS)

The Production public key resides here
The Sandbox public key resides here

Use any standard JWKS / JOSE library to verify and decode tokens: JWT / JOSE Libraries

Recommendation: Cache the JWKS response for up to 60 minutes to avoid unnecessary network calls.

Example (TypeScript using `jose`)

// Fetch the JWKS from /.well-known/jwks.json
const jwks = await getJWKS()

// Create a verifier from the JWKS
const verifier = jose.createLocalJWKSet(jwks)

// Verify signature and extract payload
const { payload, protectedHeader } = await jose.jwtVerify(
  token.token,
  verifier,
  {
    issuer: 'https://app.skyfire.xyz',
  }
)

Claims to Verify

Below are the required validations per token type.

Common Validations (All Token Types)

Always verify:

Signature is valid
alg is ES256
kid is set to a valid Key ID discoverable via the issuer's JWKS
- The Production public key resides here
- The Sandbox public key resides here
typ is expected token type; one of kya+jwt, pay+jwt, or kya-pay+jwt
iat is a 10-digit epoch-seconds value in the past
iss is
- https://app.skyfire.xyz (when env is production)
- https://app-sandbox.skyfire.xyz (when env is sandbox)
jti is a UUID
exp is a 10-digit epoch-seconds value now or in the future
env is production (or sandbox in sandbox)

Optionally you can also verify:

aud is a UUID (Seller Agent Account ID)
sub is a UUID (Buyer Agent Account ID)
Service targeting validation:
- ssi equals your Skyfire Seller Service ID (if you have onboarded to Skyfire for Payments Processing) OR
- sdm equals your website / service's domain

`kya` Tokens (`typ = kya+jwt`)

In addition to the common validations:

hid contains the human principal’s identity fields (JSON object)
apd (optional) contains agent platform's identity fields (JSON object)
aid contains agent identity fields (JSON object)

Use kya tokens for identity verification only.

`pay` Tokens (`typ = pay+jwt`)

In addition to the common validations:

val > 0
amt > 0
cur is USD
stp is one of:
- coin
- card
- bank
sti contains settlement metadata (JSON object)
spr matches the price configured in your seller service (if you have onboarded to Skyfire for Payments Processing)
sps matches your configured pricing scheme (if you have onboarded to Skyfire for Payments Processing), one of:
- pay_per_use
- subscription
- pay_per_mb
- custom

Use pay tokens for payment collection only.

`kya-pay` Tokens (`typ = kya-pay+jwt`)

Perform both kya and pay validations.

These tokens contain both identity and payment information.

Reference Implementations

TypeScript: https://github.com/skyfire-xyz/kyapay/tree/main/code-examples/verifyKyaPayToken/typescript

Python: https://github.com/skyfire-xyz/kyapay/tree/main/code-examples/verifyKyaPayToken/python