Authentication matrix

Canonical authentication patterns by API surface, including known header formats and ownership boundaries.

Use this matrix to choose authentication behavior by interface instead of applying one auth pattern everywhere.

Scope

  • Includes auth patterns explicitly documented in current IXO docs.
  • Distinguishes protocol gateways from service APIs.
  • Centralizes header examples used across guides and API pages.

Auth by API surface

Blockchain RPC API
  • Auth ownership: Node / operator policy
  • Known documented pattern: Deployment-specific
  • Header example: Confirm per endpoint and operator policy
Blockchain REST API (gRPC gateway)
  • Auth ownership: Node / operator policy
  • Known documented pattern: Deployment-specific
  • Header example: Confirm per endpoint and operator policy
IXO Blocksync GraphQL API
  • Auth ownership: Service operator policy
  • Known documented pattern: Service-specific credential model
  • Header example: Confirm service deployment requirements
Matrix state bot API
  • Auth ownership: Service operator policy
  • Known documented pattern: Service-specific credential model
  • Header example: Confirm service deployment requirements
Registry API
  • Auth ownership: Service operator policy
  • Known documented pattern: Historical Basic auth example
  • Header example: Authorization: Basic <base64(username:password)>
Emerging Platform API (OpenAPI set)
  • Auth ownership: Service operator policy
  • Known documented pattern: Unauthorized responses defined in schema
  • Header example: Confirm active header contract for deployment
USSD gateway API
  • Auth ownership: Deployer / reverse proxy
  • Known documented pattern: Often unauthenticated at app layer; restrict at network edge
  • Header example: (no default header — use network controls in production)

Common header formats in docs

Authorization: Bearer <token>
X-API-Key: <api_key>
Authorization: Basic <base64(username:password)>
Warning

Do not treat any one header as globally valid across all IXO interfaces.

Secret management

  • Environment variables — Load API keys, Basic passwords, Matrix tokens, and database URLs from env or a secrets manager; never commit them to git or embed them in client-side bundles.
  • Rotation — When operators rotate credentials, update your deployment config first, then redeploy clients. Prefer short-lived tokens where the service supports them.
  • Least privilege — Use separate credentials per environment (dev/staging/prod) and per integration so a leak does not span systems.
  • Logs — Strip authorization headers and tokens from application logs and exception reports.

Credential-source guidance

  • Protocol gateways: get access policy from your target node/network operator.
  • Service APIs: get credentials from the service operator for the environment you use.
  • Confirm endpoint and environment mappings in /reference/networks-and-endpoints.
  • Networks and endpoints: /reference/networks-and-endpoints
  • Product and SDK map: /reference/product-and-sdk-map
  • API authentication overview: /api-reference/authentication