KYA tokens issued by Skyfire are encrypted and sent directly by the agent in the custom HTTP header skyfire-pay-id over a secure HTTPS connection. kya tokens are RFC-7515 and RFC-7519 compliant signed JWTs.

Skyfire publishes its JWKS file at https://app.skyfire.xyz/.well-known/jwks.json. The file doesn't change very often and can be cached for an hour.
Signing ensures that the JWTs are tamper-proof
End-to-end HTTPS encryption ensures that malicious intermediaries cannot extract tokens from the request headers

Any standard JWKS / JOSE library can be used to verify and extract data from the tokens.

// Get the key set from .../.well-known/jwks.json
const jwks = await getJWKS()

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

JWT Header Validation

Claim	Validation
alg	JWTs MUST be signed using allowed JWA algorithms (currently, `ES256`).
kid	The `kid` claim MUST be present, and set to a valid Key ID discoverable via the issuer's (payload `iss` claim) JWK S
typ	The `typ` header parameter value MUST be one of: `kya+jwt`, `pay+jwt`, or `kya-pay+jwt`.

JWT Payload Validation

First, verify the JWT signature. Valid JWTs MUST be signed with a valid key belonging To the token's issuer (iss claim).

Then, validate claims:

Claim	Validation
iss	Ensure that the token is signed by the expected valid issuer.
exp	The verifier MUST validate that the token has not expired, within the verifier's clock drift tolerance.
iat	The verifier MUST validate that the token was issued in the past, within the verifier's clock drift tolerance.
jti	Ensure that the `jti` claim is present, and is a UUID.
aud	Ensure that the `aud` identifies the recipient as the intended audience.
env	Ensure that the Environment claim is set to an expected and use case appropriate value (such as `production` or `sandbox`)

Reference Implementations

Validation and Claim Extraction

Skyfire publishes its JWKS file at https://app.skyfire.xyz/.well-known/jwks.json. The file doesn't change very often and can be cached for an hour.
Signing ensures that the JWTs are tamper-proof
End-to-end HTTPS encryption ensures that malicious intermediaries cannot extract tokens from the request headers

Any standard JWKS / JOSE library can be used to verify and extract data from the tokens.

// Get the key set from .../.well-known/jwks.json
const jwks = await getJWKS()

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

JWT Header Validation

Claim	Validation
alg	JWTs MUST be signed using allowed JWA algorithms (currently, `ES256`).
kid	The `kid` claim MUST be present, and set to a valid Key ID discoverable via the issuer's (payload `iss` claim) JWK S
typ	The `typ` header parameter value MUST be one of: `kya+jwt`, `pay+jwt`, or `kya-pay+jwt`.

JWT Payload Validation

First, verify the JWT signature. Valid JWTs MUST be signed with a valid key belonging To the token's issuer (iss claim).

Then, validate claims:

Claim	Validation
iss	Ensure that the token is signed by the expected valid issuer.
exp	The verifier MUST validate that the token has not expired, within the verifier's clock drift tolerance.
iat	The verifier MUST validate that the token was issued in the past, within the verifier's clock drift tolerance.
jti	Ensure that the `jti` claim is present, and is a UUID.
aud	Ensure that the `aud` identifies the recipient as the intended audience.
env	Ensure that the Environment claim is set to an expected and use case appropriate value (such as `production` or `sandbox`)