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

Older integrations may use the skyfire-pay-id header but this is deprecated and being replaced.

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

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

High Level Validation Flow

At a high level, the flow looks like:

1. Extract the token from the request header (kyapay-token or skyfire-pay-id).
2. Verify the signature using Skyfire’s public keys (JWKS).
   1. Production: https://app.skyfire.xyz/.well-known/jwks.json
   2. Sandbox (for testing): https://app-sandbox.skyfire.xyz/.well-known/jwks.json
3. Decode the token
4. Validate the claims. This can help you ensure the token is:
   1. The intended token type (typ)
   2. From the correct environment (env, iss)
   3. 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.

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:

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:

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 [email protected].

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:

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.