If your seller service is defined using an OpenAPI specification, you should clearly document how Skyfire tokens must be passed and validated.

Explicit documentation ensures buyer agents can automatically generate and include the correct tokens when calling your API.

See an example OpenAPI spec, here!

Ways to Require a Header

In both approaches, you should avoid using the standard Authorization header, as it may conflict with existing authentication middleware and tooling. Instead, use a dedicated header such as skyfire-pay-id.

Security Scheme

Define a security scheme:

{
  "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: []

What this does:

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

Required Header Parameter

Explicitly define a header as a parameter:

{
  "paths": {
    "/example": {
      "get": {
        "parameters": [
          {
            "name": "skyfire-pay-id",
            "in": "header",
            "description": "Skyfire token header. This service accepts kya, pay, or kya-pay tokens.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  }
}

paths:
  /example:
    get:
      parameters:
        - name: skyfire-pay-id
          in: header
          description: Skyfire token header. This service accepts kya, pay, or kya-pay tokens.
          required: true
          schema:
            type: string

What this does:

Requires the client to include the header for that specific operation
Must be defined per endpoint
Treats the header as a standard input parameter (not authentication)
Does not integrate with auth tooling or flows

Specify Accepted Token Types

For each endpoint, describe which Skyfire tokens are accepted so integrators and buyer agents know what to send.

This can usually be documented in one of two lightweight ways:

In the header description itself
With an optional vendor extension such as x-skyfire-token-type

In many cases, the description alone is enough. If your endpoint behavior is simple, adding clear text like “Accepts pay or kya-pay tokens” is often sufficient 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 & payment)
Whether one token type is required vs multiple token types 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": {
      "SkyfirePayId": {
        "type": "apiKey",
        "in": "header",
        "name": "skyfire-pay-id",
        "description": "Skyfire token header. This service accepts pay, or kya-pay tokens."
      }
    }
  },
  "security": [
    {
      "SkyfirePayId": []
    }
  ],
  "paths": {
    "/purchase": {
      "post": {
        "summary": "Create a purchase",
        "description": "Creates a purchase for the requested resource.",
        "security": [
          {
            "SkyfirePayId": []
          }
        ],
        "x-skyfire-token-type": ["pay", "kya-pay"]
      }
    }
  }
}

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

security:
  - SkyfirePayId: []

paths:
  /purchase:
    post:
      summary: Create a purchase
      description: Creates a purchase for the requested resource.
      security:
        - SkyfirePayId: []
      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": "skyfire-pay-id",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Skyfire toekn 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: skyfire-pay-id
          in: header
          required: true
          schema:
            type: string
          description: Skyfire token header. This service accepts ky or kya-pay tokens.
      x-skyfire-token-type:
        - kya
        - kya-pay

Recommended Error Handling

Your specification should also describe error responses for:

Missing token
Invalid or expired token
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 allow buyer agents to:

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

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