2S Io Authentication

generated: '2026-09-19'
method: searched
source: openapi/2s-io-openapi.json
docs:
- https://2s.io/learn/x402
- https://2s.io/llms.txt
- https://2s.io/learn/x402/mcp
- https://2s.io/.well-known/2s-attestation.json
summary:
  types:
  - apiKey
  api_key_in:
  - header
  model: >-
    Payment in place of authentication. There are no accounts, no API keys to issue, no OAuth and no OIDC —
    the single securityScheme is an apiKey-typed header that carries a signed x402 payment, applied to all
    575 operations. Identity, where it matters (wallet-scoped store/lock/queue/watchers), is the address that
    paid. Anonymous access exists only through trial mode (one free real call per endpoint per hour) and
    through the free discovery documents.
schemes:
- name: x402Payment
  type: apiKey
  in: header
  parameter: PAYMENT-SIGNATURE
  applied_to: 'all 575 operations (security [{x402Payment: []}] on each; no global security block)'
  description: 'x402 protocol v2: base64-encoded PaymentPayload. Call any paid endpoint without auth to receive a 402 with a multi-network PaymentRequirements envelope. Sign for either rail: EIP-3009 transferWithAuthorization (Base USDC) OR a partial SPL token transfer (Solana USDC). Retry with PAYMENT-SIGNATURE header. X-PAYMENT is also accepted for v1 buyer clients. See https://x402.org.'
  flow:
  - 'Request with no credential → HTTP 402, body = X402PaymentRequiredV2 {x402Version 2, accepts[], resource, error, extensions.bazaar}, header PAYMENT-REQUIRED (same envelope, base64), x-payment-requirements: x402 (observed live 2026-09-19).'
  - 'Sign a USDC authorization for accepts[].amount (atomic units, 6 decimals) on the chosen rail: Base (eip155:8453) EIP-3009 transferWithAuthorization with the EIP-712 domain in accepts[].extra; or Solana (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) partial SPL transfer with the feePayer in accepts[].extra.'
  - 'Retry the identical request with PAYMENT-SIGNATURE: <base64 payload> (X-PAYMENT for v1 clients) → 200 + X-PAYMENT-TX. The facilitator (https://api.cdp.coinbase.com/platform/v2/x402) verifies off-chain, the handler runs, settlement follows on-chain and the facilitator pays gas.'
  alternate_scheme: 'upto — on AI endpoints, a Permit2 authorization for the quoted maximum, settled at actual usage; appears as an extra accepts[] entry after exact.'
  sources:
  - openapi/2s-io-openapi.json
  - https://2s.io/learn/x402
- name: trial-mode
  type: none
  in: query or header
  parameter: 'trial=1 | X-2s-Trial: 1'
  applied_to: all operations except feedback_send
  description: 'Bypasses payment for one free real call per endpoint per hour (response marked meta.trial). Not an authentication scheme — an allowance; recorded so an agent knows the anonymous path exists. Declared as components.parameters.TrialMode.'
  sources:
  - openapi/2s-io-openapi.json
  - https://2s.io/llms.txt
- name: hosted-mcp-signer
  type: apiKey
  in: header
  parameter: X-EVM-Private-Key
  applied_to: https://2s.io/mcp (hosted MCP server) only
  description: >-
    The hosted MCP server signs x402 payments on the caller's behalf, so it takes the caller's EVM private key
    (funded with USDC on Base) as a request header. The provider's own docs warn: "a hosted signer means your key
    transits 2s infrastructure — for keys that never leave your machine, prefer the local SDK / npx". Not used by
    the REST API. initialize and tools/list need no header at all.
  sources:
  - https://2s.io/learn/x402/mcp
  - mcp/2s-io-mcp.yml
credentials_and_secrets:
  api_keys: none — the service issues no credentials
  wallet_key: 'the caller''s own EVM (EVM_PRIVATE_KEY) or Solana key, held by the caller''s client; the SDKs accept a viem signer or a raw private key'
  key_prefixes: not applicable
  rotation: not applicable
response_authenticity:
  mechanism: 'optional response attestation — ?sign=1 adds X-2s-Attestation-* headers with an EIP-191 signature by 0xC20d180f1d8aaf2117d13252C5E803895F0D7717 over sha256(body); the body is unchanged'
  docs: https://2s.io/.well-known/2s-attestation.json
  callback_signing: 'watcher / schedule / pub-sub deliveries are EIP-191-signed by the provider''s published key (X-2s-Signature)'
oauth: null
oidc: null
mtls: null
notes:
- The security scheme is declared with type apiKey because OpenAPI has no payment type; semantically it is a per-request bearer of value, not a credential. Nothing to store, rotate or leak on the 2s side.
- No /.well-known/oauth-authorization-server, /.well-known/openid-configuration or /.well-known/oauth-protected-resource is served (all 404).