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
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
jti is a UUID
aud matches your Seller Agent Account ID
sub is a UUID (Buyer Agent Account ID)
exp is a 10-digit epoch-seconds value now or in the future
env is production (or sandbox in sandbox)

Service targeting validation (one must match):

ssi equals your Skyfire Seller Service ID
OR
sdm equals your seller domain

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

In addition to the common validations:

hid contains the human principal’s identity fields (JSON object)
apd contains buyer agent platform identity fields (JSON object)
aid contains buyer 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
sps matches your configured pricing scheme, one of:
- pay_per_use
- subscription
- pay_per_mb
- custom

Use pay tokens for payment enforcement 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