Skyfire tokens are standard signed JWTs. When a request reaches your service, it may include a token in the skyfire-pay-id header.

Before acting on the request, your service must verify the token and validate its contents.

Without these checks, your service may accept forged, expired, or mis-targeted tokens.

High Level Validation Flow

At a high level, the flow looks like:

Extract the token from the request header (skyfire-pay-id).
Verify the signature using Skyfire’s public keys (JWKS).
Decode the token
Validate the claims. This can help you ensure the token is:
1. Intended for your service (sdm)
2. The intended token type (typ)
3. From the correct environment (env, iss)
4. Still valid (iat, exp)

Only after all of these checks pass should your service authorize access and/or collect payment.

Token Format

Skyfire tokens are signed JSON Web Tokens (JWTs). Each token contains:

A header describing how the token was signed
A payload containing identity and/or payment claims
A signature used to verify authenticity

All Skyfire tokens are signed using:

Algorithm: ES256

Signature Verification (JWKS)

To verify the token, your service must use the Skyfire public keys published via JWKS (JSON Web Key Set).

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

JWKS File

Public keys for JWT verification.

https://app.skyfire.xyz/.well-known/jwks.json

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

See a TypeScript example using the jose library:

// 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

Once the token passes signature verification, decode it to access its header and payload claims.

Header Claims

For token headers, we recommend validating:

Claim	Validation
`typ`	Matches your accepted token types. One of `kya+jwt`, `pay+jwt`, `kya-pay+jwt`.

For general information about the header of Skyfire tokens, see this page .

Payload Claims

There are common claims that exist across all Skyfire tokens, regardless of token type. Across these claims, we recommend validating:

Claim	Validation
`env`	Is `production` for production integrations. Is `sandbox` for sandbox integrations.
`sdm`	Is your website/service's root domain.
`iat`	Is a 10-digit epoch-seconds value in the past.
`jti`	Is a UUID.
`exp`	Is a 10-digit epoch-seconds value now or in the future

For more general information about these claims, see this page.

The claims below are only applicable in specific cases. You will not typically validate these. For more information, contact support@skyfire.xyz.

Claim	Validation
`ssi`	Not always applicable - Is your Skyfire Seller Service ID (if you have onboarded your Seller Service to Skyfire for, for example, Payments Processing)
`aud`	Not always applicable - Is your Skyfire Seller Agent ID (if you have onboarded your Seller Service to Skyfire for, for example, Payments Processing)
`sub`	Not always applicable - Matches the expected Buyer Agent ID (if you are only allowing specific buyer agents / buyer agent platforms)

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

In addition to the common validations, consider validating identity-specific claims:

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

For more general information about kya claims, see this page.

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

In addition to the common validations, consider validating payment-specific claims:

Claim	Validation
`val`	Is greater than 0.
`amt`	Is greater than 0.
`cur`	Is `USD`
`stp`	Matches your expected settlement type. One of `coin`, `card`, `bank`.
`sti`	Includes `sti.verified: true`. Additional validations encouraged.
`spr`	Matches your configured seller service price (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`.

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

Perform both kya and pay validations.

Reference Implementations

The following examples demonstrate how to verify Skyfire tokens and perform common claim validations.

They are intended as reference implementations. You should adapt validation logic to your service’s requirements and risk tolerance.

Verify a Token Created to an External Seller

See a KYA token validation implementation to an external seller.

Verify a Token Created to an Onboarded Seller Service

See a KYA-PAY token validation implementation to a Skyfire-onboarded seller service.