Integrating KYAPay Tokens into your Seller Services

Each unique buyer agent that seeks to buy from your seller service, will provide a KYAPay token to your seller service. This token will identify the buyer uniquely. The buyer agent's unique ID will be in the sub claim and the buying human's identity will be in the bid claim.

On your (seller's) end, you have the option to follow one of three typical paths from least effort to most effort (and also most secure).

1. Require the agent to provide a kya token with each request typically in an HTTP header (we recommend naming the header skyfire-pay-id for consistency)

   1. In this case, your service can use the kya token itself to authorize the agent's access and optionally create an account for the agent
   2. When the agent wants to make a purchase, your service would require a kya+pay token to be provided (also typically in the header of the purchase request)

2. Add a /create-acount-and-or-login endpoint

   1. In this case, this endpoint will require the agent to provide a kya token, typically in the HTTP header of the request
   2. Your service will validate and extract the buyer's identity from the token and can then either create the agent's account and log the agent in or if the account already exists, then just log the agent in
   3. In this case, your service would typically return an Access token or Session token to the agent for it to use in future requests
   4. When the agent wants to make a purchase, your service would require a pay token to be provided (also typically in the header of the purchase request)

3. Add a /create-acount-and-or-login endpoint and require a password

   1. This is an extension of 2 (above)
   2. In this case, this endpoint will require the agent to provide a kya token, typically in the HTTP header of the request
   3. Additionally this endpoint will require the agent to pass a password in the body of the request
   4. Your service will validate and extract the buyer's email address from the token (bid.skyfireEmail) and the password from the request body
   5. Your service will then use your CIAM's APIs to create an account and / or login the agent using the email address and password
      1. This is typically a straightforward token exchange process and we can walk you through how to do this with your CIAM
      2. This approach exchanges a kya token for an access token in the CIAM
   6. The agent is expected to know whether it already has an account, and if so, to provide the correct password to login instead of creating an account
   7. In this integration the human principal, behind the agent, gains the ability to also login to your service

We recommend requiring Skyfire / KYAPay tokens to be passed to your service via an HTTP Header named skyfire-pay-id. You are welcome to use any other header or body parameter as well. We recommend NOT using the Authorization header to avoid conflicting with existing functionality that may already use that header.

Other paths may be possible and we are happy to discuss and support you in meeting your needs.