Authentication

Search1API accepts OAuth access tokens and user-managed API keys as bearer credentials. Send either one in the same header to authenticated endpoints at https://api.search1api.com:

Authorization: Bearer YOUR_ACCESS_TOKEN_OR_API_KEY

Choose an authentication method

Use OAuth 2.1 when an AI agent, native CLI, or OAuth-aware MCP client needs a user to approve access. The client can discover the authorization server, register as a public client, use Authorization Code + PKCE, and refresh access without asking the user to copy a long-lived API key.

Use an API key for fixed server-to-server integrations, CI, existing SDK configurations, or clients that do not support OAuth discovery yet. API keys remain fully supported.

Both methods use the same Search1API account, credit balance, billing rules, and rate limits.

OAuth 2.1

Start with the protected resource used by the client:

• REST API: https://api.search1api.com/.well-known/oauth-protected-resource
• Hosted MCP: https://mcp.search1api.com/.well-known/oauth-protected-resource

These documents advertise the Search1API authorization server. A 401 response for an invalid bearer credential also includes a WWW-Authenticate challenge with the applicable resource_metadata URL. The Hosted MCP endpoint sends the same discovery challenge when no credential is present.

Search1API supports Dynamic Client Registration, Authorization Code with PKCE (S256), access and refresh tokens, and token revocation. A human account owner must still sign in and approve the client; dynamic registration does not silently create a Search1API user.

For the complete protocol flow and endpoint list, read the agent-friendly auth.md.

First-party CLI

The Search1API CLI implements the complete public-client flow:

s1 login
s1 config show

It dynamically registers, opens the browser for approval, stores the resulting OAuth credentials locally, and refreshes expired access tokens automatically. See CLI for installation and fallback options.

Hosted MCP

OAuth-aware MCP clients can point directly at https://mcp.search1api.com/mcp and follow the server's protected-resource challenge. Clients without OAuth support can continue using an API key. See MCP server for both configurations.

API keys

Get a key

Sign in at dashboard.search1api.com, open API Keys, and create a key. The dashboard lets you label, reveal, copy, and delete existing keys.

Keep keys server-side

Treat a key like a password. Store it in an environment variable or secret manager, and never expose it in browser code, mobile binaries, logs, or a public repository.

Separate keys by workload

Use different keys for environments or services so you can identify traffic and revoke one integration without interrupting the others. Add a clear label in the dashboard, such as production-api, staging, or claude-mcp.

All keys owned by the same account draw from the same credit balance. Separate keys improve attribution and revocation; they do not create separate balances.

Rotate or revoke a key

There is no in-place rotation action. To replace a key:

1. Create a new key.
2. Update the application or integration.
3. Confirm requests succeed with the new key.
4. Delete the old key.

Deleting a key revokes it. Requests that continue using it return 401 Unauthorized.

Authentication failures

An invalid, expired, or revoked bearer credential returns 401. OAuth-aware clients should use the accompanying WWW-Authenticate metadata to discover authorization or refresh an expired token before retrying.

A request with no bearer credential currently receives a 402 payment challenge on paid API endpoints because Search1API also supports pay-per-request payment protocols. The Hosted MCP endpoint instead returns a 401 OAuth discovery challenge when no credential is present.

See Error handling for response bodies and recovery guidance.