# Authentication

> Choose OAuth 2.1 or API keys, send bearer credentials safely, and recover from authentication failures.

Canonical URL: https://s1.dev/docs/essentials/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`:

```http
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`](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)

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`](https://s1.dev/auth.md).

### First-party CLI

The Search1API CLI implements the complete public-client flow:

```bash
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](https://s1.dev/docs/integrations/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](https://s1.dev/docs/integrations/mcp) for both configurations.

## API keys

### Get a key

Sign in at [app.s1.dev](https://app.s1.dev), 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.

> **warn:** Anyone who has the key can make requests against your account balance. If a key leaks, replace it and delete the old key immediately.

### 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](https://s1.dev/docs/essentials/error-handling) for response bodies and recovery guidance.