# Search1API auth.md — OAuth for Agents, MCP, and CLI

> Search1API supports standard OAuth 2.1 for agents, MCP clients, and native CLI clients. A human account owner signs in with Search1API, reviews the consent screen, and authorizes the client. Existing user-managed API keys remain supported for backward compatibility.

## Machine-readable discovery

Start at the protected resource used by your client:

- REST API: [https://api.search1api.com/.well-known/oauth-protected-resource](https://api.search1api.com/.well-known/oauth-protected-resource)
- Hosted MCP: [https://mcp.search1api.com/.well-known/oauth-protected-resource](https://mcp.search1api.com/.well-known/oauth-protected-resource)
- Authorization server: [https://clerk.search1api.com/.well-known/oauth-authorization-server](https://clerk.search1api.com/.well-known/oauth-authorization-server)

Protected Search1API responses also advertise the metadata URL in the `WWW-Authenticate` header defined by RFC 9728.

## Agent registration contract

This is the complete registration path for autonomous agents, OAuth-aware MCP clients, and native CLI clients. It uses OAuth 2.0 Dynamic Client Registration followed by human account authorization; it does not create a Search1API user without consent.

```json
{
  "audience": "agents, OAuth-aware MCP clients, and native CLI clients",
  "register_uri": "https://clerk.search1api.com/oauth/register",
  "registration_methods_supported": ["oauth_dynamic_client_registration"],
  "identity_types_supported": ["oauth_user_authorization"],
  "credential_types_supported": ["oauth_access_token", "oauth_refresh_token"],
  "authorization_uri": "https://clerk.search1api.com/oauth/authorize",
  "token_uri": "https://clerk.search1api.com/oauth/token",
  "revocation_uri": "https://clerk.search1api.com/oauth/token/revoke"
}
```

Client registration does not require an email or pre-existing API key. After registration, the agent opens the authorization URL so the account owner can sign in or create an account and approve access. The resulting Bearer access token is sent in the `Authorization` header; a refresh token is issued only when `offline_access` is requested.

## Recommended OAuth flow

1. Fetch the protected resource metadata and choose its advertised authorization server.
2. Fetch the authorization-server metadata.
3. Register the client using the advertised `registration_endpoint`, including every scope the client will request (for example, `scope: "openid offline_access"`). Public clients must not rely on a client secret.
4. Generate a PKCE verifier and an `S256` code challenge.
5. Open the advertised authorization endpoint with `response_type=code`, the registered `client_id`, a loopback or HTTPS redirect URI, `state`, and the PKCE challenge.
6. The account owner signs in or creates a Search1API account and approves access.
7. Exchange the authorization code at the advertised token endpoint using the original PKCE verifier.
8. Send the access token as a Bearer token. Request `offline_access` and securely retain the refresh token when long-running access is needed.

Example protected request:

```http
Authorization: Bearer OAUTH_ACCESS_TOKEN
```

```bash
curl -X POST https://api.search1api.com/search \
  -H "Authorization: Bearer $SEARCH1API_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"latest AI agent standards"}'
```

OAuth tokens are mapped to the same Search1API user and credit balance shown in the dashboard. Clients should refresh expired access tokens and repeat authorization only when the refresh grant is unavailable or revoked.

## Search1API CLI

The first-party CLI implements this OAuth flow directly:

```bash
s1 login
```

The CLI discovers the protected resource and authorization server, dynamically registers as a public native client, generates an `S256` PKCE challenge, opens the browser for user approval, exchanges the code, and refreshes expired access tokens automatically.

Check the active credential source with:

```bash
s1 config show
```

Use `s1 login --no-browser` when the CLI should print the authorization URL instead of launching a browser. The loopback callback must still be reachable on the machine running `s1`.

## Hosted MCP

OAuth-aware MCP clients can connect directly and discover authorization from the protected-resource challenge:

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

MCP endpoint: [https://mcp.search1api.com/mcp](https://mcp.search1api.com/mcp)

## Legacy API keys

Existing integrations may continue to send a Search1API key:

```http
Authorization: Bearer YOUR_SEARCH1API_KEY
```

Create, rotate, and revoke keys in [the Search1API dashboard](https://dashboard.search1api.com). Header authentication is preferred; putting credentials in URL query parameters can expose them in logs and shell history.

The CLI also retains manual API-key fallbacks for scripts and CI:

```bash
s1 config set-key YOUR_SEARCH1API_KEY
# or
export SEARCH1API_KEY=YOUR_SEARCH1API_KEY
```

## Security requirements

- Use Authorization Code with PKCE (`S256`); do not use the implicit grant.
- Verify `state` before exchanging the authorization code.
- Use an exact registered redirect URI. Native clients should use an ephemeral loopback port where supported.
- Store refresh tokens in the operating system credential store or an equivalently protected secret store. The Search1API CLI writes its local configuration with owner-only permissions on Unix-like systems.
- Never embed access tokens, refresh tokens, API keys, or client secrets in public browser code or source control.
- Revoke authorization or rotate an API key if a credential may have been exposed.

## Other agent interfaces

- API catalog: [https://www.search1api.com/.well-known/api-catalog](https://www.search1api.com/.well-known/api-catalog)
- OpenAPI schema: [https://api.search1api.com/openapi.json](https://api.search1api.com/openapi.json)
- MCP server card: [https://www.search1api.com/.well-known/mcp/server-card.json](https://www.search1api.com/.well-known/mcp/server-card.json)
- Agent Skills index: [https://www.search1api.com/.well-known/agent-skills/index.json](https://www.search1api.com/.well-known/agent-skills/index.json)
- CLI guide: [https://www.search1api.com/docs/integrations/cli](https://www.search1api.com/docs/integrations/cli)
- Documentation: [https://www.search1api.com/docs](https://www.search1api.com/docs)