Connect AI Agents to Search1API with OAuth 2.1

If you have ever connected an AI assistant, a CLI, or an MCP server to a web API, you probably know the ritual: sign in to a dashboard, create an API key, then paste that long-lived credential into another tool.

It works. It also makes the user responsible for a job that an authorization protocol should handle. The user has to decide which key belongs in which client, rotate it if it leaks, and remember where it is still being used. The client has no standard way to discover where to sign in, refresh access, or revoke a grant.

Here is the uncomfortable truth: API keys are useful for fixed server-to-server integrations, but they should not be the only identity option for every agent client.

Search1API now supports standard OAuth 2.1 authorization across the REST API, Hosted MCP, and the first-party CLI. OAuth-aware clients can register, ask the account owner for approval, and receive refreshable access without asking the user to copy a long-lived API key. Existing API-key integrations keep working.

What the authorization flow looks like

The account owner still controls the final decision:

1. The client fetches Search1API's protected-resource metadata and discovers the authorization server.
2. It uses Dynamic Client Registration to register its redirect URI and requested scopes.
3. It opens the Search1API authorization page in a browser.
4. The account owner signs in or creates an account, reviews the request, and approves or denies it.
5. The client exchanges the authorization code using PKCE with an S256 challenge.
6. When it requests offline_access, it can also receive a refresh token for long-running work.

Dynamic registration does not mean an agent can silently create a Search1API user. The OAuth client registers itself; a human still creates or signs in to the account and approves access.

The fastest way to try it: s1 login

The first-party Search1API CLI implements the complete public-client flow. Install it and run:

curl -fsSL https://cli.search1api.com/install.sh | bash
s1 login

The CLI discovers the protected resource and authorization server, registers as a public native client, generates the PKCE challenge, and opens the browser for approval. After authorization, it stores the access and refresh tokens locally and refreshes the access token automatically when needed.

You can confirm which credential source is active with:

s1 config show

This matters because OAuth is not merely a collection of .well-known files on our server. It is a first-party login path you can use today. For CI or another environment where interactive login is not practical, s1 config set-key and SEARCH1API_KEY remain available.

Hosted MCP can discover authorization too

An OAuth-aware MCP client can start with the Search1API endpoint alone:

{
  "mcpServers": {
    "search1api": {
      "url": "https://mcp.search1api.com/mcp"
    }
  }
}

When no credential is present, Hosted MCP returns a 401 challenge pointing to its protected-resource metadata. A compatible client can follow that metadata to the authorization server, register, and start the browser approval flow.

OAuth support still depends on the MCP client. A client that does not implement protected-resource discovery or Dynamic Client Registration will not become OAuth-aware just because the server is. Those clients can continue using a Search1API API key. The Hosted MCP guide documents both paths.

Better credential lifecycles, not a second account system

An OAuth client receives a user-approved access token instead of a manually copied long-lived key. When the access token expires, a client with offline_access can use its refresh token. The authorization server also publishes a standard revocation endpoint, so clients do not have to invent their own credential lifecycle around API keys.

OAuth does not create a separate Search1API account or billing system. The token maps to the same user and credit balance shown in the dashboard. Gateway billing, minute limits, and usage queries recognize the OAuth identity. Changing the identity mechanism does not create a second balance or require a separate plan for an agent.

The machine-readable surface behind it

The authorization flow is part of a broader agent-facing discovery surface:

• OAuth Authorization Server Metadata
• OAuth Protected Resource Metadata for the REST API and Hosted MCP
• MCP Server Card
• API Catalog and OpenAPI schema
• Agent Skills index
• An agent-readable `auth.md`
• A Web Bot Auth key directory signed with HTTP Message Signatures

These endpoints give clients a place to start without scraping a rendered documentation page. The Web Bot Auth directory solves a different problem from OAuth: it publishes the Ed25519 key material used to verify its signed directory response. It complements authorization rather than replacing it.

Existing API keys are not going away

If a backend, script, CI job, or existing agent already sends Authorization: Bearer SEARCH1API_KEY, there is nothing to migrate.

API keys are still a practical choice for fixed server-side integrations and clients that do not support OAuth discovery. OAuth is the better fit when a client needs user approval, automatic discovery, and refreshable access. Search1API now supports both because the right choice depends on the integration, not on a launch announcement.

Promises such as "every MCP client now connects automatically" would be misleading. The accurate boundary is simpler: Search1API publishes and implements the standard flow; compatible clients can use it, and every other integration can keep using an API key.

---

Search1API gives AI agents web search, news, crawling, site discovery, and trending tools through one account. Use OAuth 2.1 for user-approved, refreshable access or keep your existing API key. Read the OAuth and API-key guide →