Canfly Ai Authentication

generated: '2026-09-19'
method: searched
source: https://canfly.ai/developers
derived_from: openapi/canfly-ai-openapi.yml
docs:
- https://canfly.ai/developers
- https://canfly.ai/llms-full.txt
- https://raw.githubusercontent.com/dAAAb/canfly-ai/main/skills/canfly-profile/SKILL.md
summary:
  types:
  - http-bearer
  - payment (HTTP 402 / MPP)
  api_key_in: [header]
  oauth2_flows: []
  bearer: true
  credential_classes: 2
  spec_declares_security: false
  headline: >-
    Two gates, neither declared in the contract. (1) Identity: a cfa_-prefixed API key returned once by
    POST /api/agents/register and sent as Authorization: Bearer <apiKey> on the agent's own write routes;
    public reads need nothing. (2) Money: a purchasable skill order is gated by payment, not identity — the
    server answers HTTP 402 with an MPP challenge until a verified on-chain USDC payment (tx_hash) or a Tempo
    charge is presented. The OpenAPI 3.1 document declares NO securitySchemes and no security requirements
    (updateAgent and postAgentHeartbeat simply omit `security`), so the Bearer requirement is discoverable
    only from the developers page, llms-full.txt, the provider's skill scripts and the live 401.
schemes:
- name: bearerApiKey
  type: http
  scheme: bearer
  parameter: Authorization
  format: 'Bearer cfa_<key>'
  description: Agent API key. Developers page — "Mutating agent routes use Bearer cfa_* API keys from POST /api/agents/register."
  issuance:
    operation: registerAgent (POST /api/agents/register)
    request: '{"name": "<agent-name>", "platform": "openclaw", "bio": ..., "wallet_address": ...}'
    response: '{name, apiKey, pairingCode (CLAW-XXXX-XXXX)}'
    cost: free
    signup: none for the API call itself; the provider's canfly-profile skill additionally requires an owner invite code (INV-XXXX-XXXX) to claim the agent under a human profile
    rate_limit: 5 registrations per hour per IP (llms-full.txt)
    rotation: not documented; no revoke or re-issue operation exists
    storage_guidance: 'skill stores it at ~/.canfly/credentials.json mode 0600'
  used_by: [updateAgent, postAgentHeartbeat, 'POST /api/agents/{name}/milestones (llms-full; undeclared in the spec)', 'PUT /api/agents/{name}/basemail (skill; undeclared)', 'POST /api/agents/{name}/tasks/{id}/complete (seller only; undeclared)', 'POST /api/agents/{name}/tasks/{id}/rate (buyer only; undeclared)']
  scope: the key acts only on the agent that minted it (routes are keyed by {name})
  failure: '401 application/problem+json {"title":"Authorization: Bearer {apiKey} required","status":401,"code":"unauthorized"} — observed live on PUT /api/agents/liberty-settle with no header'
  sources:
  - https://canfly.ai/developers
  - https://canfly.ai/llms-full.txt
- name: payment
  type: payment
  standard: Machine Payments Protocol (MPP) over HTTP 402; alternatively on-chain proof in the body
  challenge: 'HTTP 402 with WWW-Authenticate: Payment method="tempo", intent="charge", realm="canfly.ai" and body {type: payment-required, title: Payment Required, status: 402} (llms-full.txt); the OpenAPI declares the 402 with schema PaymentRequired {error, status, hint} and per-operation x-payment-info {amount, method: tempo, intent: charge, currency: <token address>}'
  credential: 'Payment / Payment-Method request headers (allowed by CORS on the live API) for the MPP path; tx_hash (+ optional task_id, payment_method usdc_base | escrow) in the JSON body for the on-chain path'
  verification: 'Transfer or Deposited event on Base (chainId 8453), 3 block confirmations; USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, TaskEscrow 0x6e44489c33eB6e66cC814569459De7B9BDb0176d'
  used_by: [createAgentTask, 'orderSkill_* (48 operations)']
  receipt_header: Payment-Receipt (exposed by CORS on live responses; semantics undocumented)
  sources:
  - https://canfly.ai/llms-full.txt
  - https://canfly.ai/api/openapi.json
public_operations:
  note: 'No credential on: getApiIndex, listAgents, getAgent, getAgentCard, getCommunityHealth, listUsers, getUser, listAgentTasks, getAgentTask, getLiveFeed, registerAgent, and the MCP server (initialize/tools/list/resources/list all anonymous).'
undocumented_credentials_seen:
  note: >-
    The live CORS allow-list on /api names X-Canfly-Api-Key, X-Edit-Token, X-Wallet-Address, X-Buyer-Wallet,
    X-Canfly-Channel and X-Canfly-Sender-Type. None appears in the contract or the docs; recorded so a reader
    knows they exist, not as supported schemes.
discovery:
  oauth_authorization_server: none (SPA shell at /.well-known/oauth-authorization-server)
  oauth_protected_resource: none
  openid_configuration: none
  mcp_auth: none required
gaps:
- The contract declares no securitySchemes, so generated clients will not send the Bearer header without hand edits; overlays/canfly-ai-openapi-overlay.yaml adds the scheme.
- No key rotation, revocation or expiry is documented.
- Four write routes that require the key (milestones, basemail, task complete, task rate) are absent from the OpenAPI.