--- title: "PubFi Authentication and Agent Onboarding" description: "Use PubFi public catalog reads, human-created API keys, Bearer authentication, and hosted MCP OAuth discovery without inventing a sandbox or autonomous registration flow." canonical_url: "https://stg.pubfi.ai/auth.md" --- # PubFi authentication and payment lanes > Choose one lane for each request. PubFi rejects conflicting credentials and does not fall back from one lane to another. - Public catalog and capability reads require no authentication. - Registered HTTP execution uses a PubFi API key. Protected hosted MCP tools accept one PubFi API key or one valid PubFi MCP OAuth access token. - Account-bound :free routes still require an admitted account credential and charge zero Credits. - Accountless x402 uses the explicit x402 endpoint and rejects Bearer credentials. - Provider credentials, account billing state, and payment material stay server-side. ## Agent onboarding walkthrough Start with the public catalog, then hand account setup to a human only when the selected operation requires authenticated execution. ### 1. Make the no-auth first-success request Fetch the live capability catalog without credentials. The response is the current Registry-backed execution inventory, not an authorization to call protected routes. ```sh curl --fail --silent --show-error \ https://api-stg.pubfi.ai/v1/capabilities ``` ### 2. Hand API-key creation to a human If the selected route requires a PubFi account, a human signs in, opens Dashboard API keys, and creates the key. The raw secret is shown once: copy it before continuing, store it in a secret manager, and never put it in source code, logs, prompts, or chat. - [Sign in](https://stg.pubfi.ai/login) - [Open Dashboard API keys](https://stg.pubfi.ai/dashboard#api-keys) ### 3. Use the API key as a Bearer credential Inject the human-created key as PUBFI_API_KEY, set PUBFI_REQUEST_URL to the exact protected HTTP route selected from current capability detail, and send one Authorization header. Do not mix Bearer authentication with x402 payment proof. ```sh : "${PUBFI_API_KEY:?Inject PUBFI_API_KEY from your secret manager}" : "${PUBFI_REQUEST_URL:?Set PUBFI_REQUEST_URL to the selected protected route}" curl --fail --silent --show-error \ --header "Authorization: Bearer ${PUBFI_API_KEY}" \ "${PUBFI_REQUEST_URL}" ``` ### 4. Discover hosted MCP OAuth An MCP client starts with the existing RFC 9728 protected-resource metadata, follows its authorization_servers metadata, and performs the advertised OAuth flow. PubFi auth.md does not add custom scopes or a separate registration protocol. ```sh curl --fail --silent --show-error \ https://mcp-stg.pubfi.ai/.well-known/oauth-protected-resource ``` ### Current boundaries - PubFi has no sandbox or customer test environment. Published staging infrastructure is not a disposable sandbox; use only the environment URLs that PubFi explicitly provides. - PubFi auth.md is guidance, not an autonomous registration or account-claim ceremony. It does not create, claim, rotate, or revoke an account or credential for an agent. ## Access paths ### Public discovery and contracts - Cost: No account. - Authentication: No authentication is required for these read-only public resources. - Purpose: Read Discovery, the complete Registry capability catalog, exact capability detail, Runtime OpenAPI, and public MCP catalog tools. - Use this lane to find sources and inspect current executable contracts. - Public catalog access does not authorize route execution. - The live Registry, not checked-in marketing content, owns readiness. - Next: [Open Developers](https://stg.pubfi.ai/developers). ### Registered account - Cost: Credits or account-bound :free. - Authentication: The selected credential must resolve to an admitted billing account. Exact :free variants remain account-bound and charge no Credit. - Purpose: Use a PubFi API key for HTTP execution or a PubFi API key or Supabase OAuth access token for protected hosted MCP tools. - Eligible billing accounts receive one lifetime starter grant of 1,000 Credits. Each starter allocation is valid for 365 days. - The current checked-in catalog defines 1,000 Credits for USD 1.00, valid for 365 days. - A purchase is available only when the authenticated billing response returns the exact current offer. Per-operation Credit cost comes from the live Registry. - Next: [Get API key](https://stg.pubfi.ai/login). ### Accountless x402 - Cost: Exact live route quote. - Authentication: Do not send a Bearer credential. The unsigned request receives an exact payment challenge, and the signed retry uses the environment-matched x402 lane. - Purpose: Use the explicit HTTP or MCP x402 endpoint for a route that the live Registry currently enables for accountless payment. - The live Registry, signed offer, pay-to address, asset, network, and payment challenge are authoritative. - x402 consumes no account Credits and creates no PubFi account, invoice, API key, or anonymous dashboard. - A published route can be unavailable, free, account-priced, or x402-priced. Do not infer a payment path from Discovery content. - Next: [Read the x402 guide](https://docs.pubfi.ai/getting-started/x402). ### Custom delivery - Cost: Custom terms. - Authentication: Access, commercial terms, and delivery boundaries are confirmed in writing for the selected program. - Purpose: Use a separately scoped delivery when a production program needs custom source integration, data packaging, service levels, or support. - Custom delivery does not make every indexed provider executable. - Source rights, credentials, route contracts, and acceptance stay explicit. - Contact PubFi with the workflow, data scope, and expected delivery requirements. - Next: [Discuss custom delivery](mailto:hello@pubfi.ai?subject=PubFi%20custom%20delivery). ## Runtime authority - [Capability catalog](https://api-stg.pubfi.ai/v1/capabilities) - [Runtime OpenAPI](https://stg.pubfi.ai/openapi.json) - [Hosted MCP manifest](https://stg.pubfi.ai/.well-known/mcp.json)