Invalid token

Missing claims

A token is invalid when it cannot be decrypted or when the correct type of token is sent but one or more claims required to complete a specific action is missing, This table in an earlier section illustrates some examples. Figure 4 shows the expected interaction in the case of an advanced registration with certain bid claims missing.

1. The Buyer Agent calls the Skyfire API (https://api.skyfire.xyz/api/v1/tokens) to generate a kya token not including the user principal information
2. If the API key is valid, the agent identity provider generates a token according to the criteria defined in the request without the bid claims
3. The Agent accesses a protected resource.
4. The bot/fraud detection engine extracts and validates the token. The agent attempts to create a new account for which the site requires at least the user's email address, first and last name, and a phone number. Since the bid claims are missing, the kya token is considered invalid: A response with a 403 - Deny HTTP status code is returned with a custom message in the body: See below
5. The Buyer Agent calls the Skyfire API (https://api.skyfire.xyz/api/v1/tokens) to generate a new kya token and includes the needed user principal information
6. If the API key is valid, the agent identity provider generates a token according to the criteria defined in the request with the bid claims
7. The agent retries the same action as in step 3 using the updated token
8. The bot/fraud detection engine extracts and validates the token. It extract the relevant claims to create the account.

{
	"error": "invalid kya token, some mandatory claims are missing to complete the action, please create a new kya token - https://docs.skyfire.xyz/reference/create-token, and include it in the skyfire-pay-id header with your next request"
}

Note: in this example we propose a simple integration with a generic method. However, the message on step 4 can be adjusted and more specific to guide the agent on to ensure they are able to create a token with the needed information for a successful completion of the transaction.

Corrupted token

In case the bot/fraud detection engine is unable to decrypt the token, this may happen in case the encryption keys have been updated, a customer error message will returned to the agent on step 4:

HTTP status code 403 - Deny

Message:

{
	"error": "Corrupted token, please create a new kya token - https://docs.skyfire.xyz/reference/create-token, and include it in the skyfire-pay-id header with your next request"
}