OpenAPI Specs

If your seller service is defined using an OpenAPI specification, document how Skyfire tokens must be passed and validated. Explicit documentation lets buyer agents automatically generate and include the correct tokens when calling your API.

See an example OpenAPI spec.

Older integrations may reference the skyfire-pay-id header instead of kyapay-token. It is deprecated and being replaced.

Ways to require a header

Avoid using the standard Authorization header in either approach below. It can conflict with existing authentication middleware and tooling. Use a dedicated header instead, such as kyapay-token.

Define a security scheme:

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

components:
  securitySchemes:
    SkyfireToken:
      type: apiKey
      in: header
      name: kyapay-token
      description: Skyfire token header. This service accepts kya, pay, or kya-pay tokens.

security:
  - SkyfireToken: []

A security scheme:

Defines the header as part of authentication
Applies globally to all endpoints, or can be overridden per operation
Signals to tools and clients that this is security-related
Is enforced by the security field

Specify accepted token types

For each endpoint, describe which Skyfire tokens are accepted, so integrators and buyer agents know what to send. Document this either in the header description itself, or with an optional vendor extension such as x-skyfire-token-type. In many cases, a clear description like "Accepts pay or kya-pay tokens" is enough for both human readers and generated documentation.

Document, where relevant:

Whether a kya token is required (identity only)
Whether a pay token is required (payment only)
Whether a kya-pay token is required (identity and payment)
Whether one token type is required or multiple are allowed
Any required token claims your service validates, such as sub, hid, or payment-specific fields

Using a vendor extension to specify token type (optional)

You may optionally use a vendor extension like x-skyfire-token-type to explicitly indicate expected token behavior for tooling or documentation purposes.

Security scheme example

{
  "components": {
    "securitySchemes": {
      "SkyfireToken": {
        "type": "apiKey",
        "in": "header",
        "name": "kyapay-token",
        "description": "Skyfire token header. This service accepts pay or kya-pay tokens."
      }
    }
  },
  "security": [
    {
      "SkyfireToken": []
    }
  ],
  "paths": {
    "/purchase": {
      "post": {
        "summary": "Create a purchase",
        "description": "Creates a purchase for the requested resource.",
        "security": [
          {
            "SkyfireToken": []
          }
        ],
        "x-skyfire-token-type": ["pay", "kya-pay"]
      }
    }
  }
}

components:
  securitySchemes:
    SkyfireToken:
      type: apiKey
      in: header
      name: kyapay-token
      description: Skyfire token header. This service accepts pay or kya-pay tokens.

security:
  - SkyfireToken: []

paths:
  /purchase:
    post:
      summary: Create a purchase
      description: Creates a purchase for the requested resource.
      security:
        - SkyfireToken: []
      x-skyfire-token-type:
        - pay
        - kya-pay

Required header parameter example

{
  "paths": {
    "/profile": {
      "get": {
        "summary": "Get profile",
        "description": "Returns the profile for the current user.",
        "parameters": [
          {
            "name": "kyapay-token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Skyfire token header. This service accepts kya or kya-pay tokens."
          }
        ],
        "x-skyfire-token-type": ["kya", "kya-pay"]
      }
    }
  }
}

paths:
  /profile:
    get:
      summary: Get profile
      description: Returns the profile for the current user.
      parameters:
        - name: kyapay-token
          in: header
          required: true
          schema:
            type: string
          description: Skyfire token header. This service accepts kya or kya-pay tokens.
      x-skyfire-token-type:
        - kya
        - kya-pay

Recommended error handling

Describe error responses for a missing token, an invalid or expired token, and an incorrect token type for the operation. Clear error documentation improves integration speed and reduces support overhead. See Handling Missing or Invalid Tokens.

Why this matters

Well-documented token requirements let buyer agents:

Automatically attach the correct token
Avoid conflicts with existing Authorization-based authentication systems
Enforce payment requirements correctly
Reduce integration errors

For how to validate tokens and extract claims, see Verify and Extract Data from Tokens.