Home
Guides

Integrating Tokens into Your Services

Each buyer agent that interacts with your seller service will provide a Skyfire token.

Important

Pass Skyfire tokens in a custom HTTP header:

skyfire-pay-id: <SKYFIRE_TOKEN>

Avoid using the standard Authorization header. Many services already use Authorization for their own authentication logic. Reusing it for Skyfire tokens can cause conflicts or unintended behavior.

On the seller side, you can follow one of three integration paths depending on your desired level of control and security.


1. Require tokens on every request (Recommended)

Require the agent to provide a Skyfire token (kya, pay, and/or kya-pay) with each request, typically in the skyfire-pay-id header.

OpenAPI spec example:

{
  "components": {
    "securitySchemes": {
      "SkyfirePayId": {
        "type": "apiKey",
        "in": "header",
        "name": "skyfire-pay-id",
        "description": "Skyfire token header. This service accepts kya, pay, or kya-pay tokens."
      }
    }
  },
  "security": [
    {
      "SkyfirePayId": []
    }
  ]
}
components:
  securitySchemes:
    SkyfirePayId:
      type: apiKey
      in: header
      name: skyfire-pay-id
      description: Skyfire token header. This service accepts kya, pay, or kya-pay tokens.

security:
  - SkyfirePayId: []

For more info, see OpenAPI Specs.

In this approach:

  • Your service validates the Skyfire token to authorize the agent.
  • You may support charging flows tied to pay or kya-pay tokens.

This is the simplest and most common integration pattern.


2. Add a /create-account-and-or-login Endpoint

In this model, your service uses a Skyfire identity token (kya and/or kya-pay) to provision or authenticate accounts.


Flow:

  1. The agent calls your /create-account-and-or-login endpoint with a Skyfire identity token in the skyfire-pay-id header.
  2. Your service validates the token and extracts the buyer’s identity.
  3. You create an account if one does not exist, or log the agent into an existing account.
  4. You return your own session or access token for future requests.
  5. When a purchase is required, the agent provides a kya-pay token.

This model is useful if you maintain persistent accounts or user state.


3. Add account creation + password requirement

This is an extension of Option 2 and provides additional security and flexibility.

Flow:

  1. The agent calls /create-account-and-or-login with a Skyfire identity token.
  2. The agent also provides a password in the request body.
  3. Your service validates the token and extracts the human buyer's identity (for example, hid.email).
  4. You create or authenticate the account using your existing CIAM or authentication system.
  5. The kya or kya-pay token may be exchanged for an internal access token.
  6. The agent is expected to log in with the correct password if the account already exists.

In this integration, the human principal behind the agent can also log directly into your service.


Additional Notes

  • Tokens should be passed via HTTP headers (recommended) or body parameters.
  • Other integration paths may be possible — we’re happy to support your specific use case.