Authentication

SheetBase has two MCP authentication paths. Both resolve to the same SheetBase user, then use that user’s connected Google account when a Sheets or Drive tool runs. Google is the only sign-in method for the SheetBase dashboard.

The canonical MCP endpoint is:

https://sheetbase.flonest.app/api/mcp

Auth paths at a glance

Do not send both an OAuth bearer token and an API key in the same request. SheetBase rejects mixed credentials.

Path 1 — OAuth for interactive MCP clients

SheetBase uses Better Auth’s stable oauthProvider() and jwt() plugins. The OAuth Provider handles client registration, PKCE authorization, consent, refresh tokens, and standards-based discovery. JWT access tokens are verified locally against the exact SheetBase issuer and MCP resource.

OAuth identity

A token must be issued by SheetBase, include the MCP resource as an audience, and include all required scopes. Invalid signatures, expired tokens, future-dated tokens, wrong issuers, wrong audiences, opaque tokens, and incomplete scopes are rejected.

Discovery endpoints

MCP clients discover the flow automatically from these routes:

GET /.well-known/openid-configuration
GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource/api/mcp

The discovered authorization endpoints live under /api/auth/oauth2/*, including client registration, authorization, token exchange, refresh, revocation, and user information.

Flow

MCP client
    │
    ├─ Discovers the SheetBase authorization server and MCP resource
    ├─ Registers a guarded redirect URI
    ├─ Opens the browser for sign-in
    ├─ Requests consent using PKCE
    ├─ Receives a resource-bound JWT and refresh token
    └─ Calls the MCP endpoint with Authorization: Bearer <token>

The consent page shows the requesting client and the signed-in SheetBase account. Redirect addresses must use HTTPS, except for standard loopback HTTP addresses used by installed local clients.

One-time reconnect after the OAuth security migration

The stable OAuth Provider uses fresh client and token records. Existing OAuth clients and tokens from the retired provider are intentionally invalidated, so interactive MCP clients must reconnect once.

User accounts remain, Google account connections remain, sessions remain, and API keys remain. Follow Reconnect SheetBase OAuth for the client-side steps.

Path 2 — API Key (x-api-key)

Generate an API key from your dashboard at https://sheetbase.flonest.app/dashboard. The key is shown once—copy it immediately and store it securely.

curl https://sheetbase.flonest.app/api/mcp \
  -H "x-api-key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

For MCP clients that support custom headers:

{
  "mcpServers": {
    "sheetbase": {
      "url": "https://sheetbase.flonest.app/api/mcp",
      "headers": {
        "x-api-key": "YOUR_KEY_HERE"
      }
    }
  }
}

API keys resolve to the same SheetBase user context as OAuth. Existing API keys are not invalidated by the OAuth Provider migration.

Name keys clearly, such as CI pipeline or Cursor headless, so one key can be revoked without affecting other clients. Never paste a key into a URL, issue, log, or chat message.

Google OAuth scopes

The Google account connection is separate from the MCP client authorization flow.

SheetBase requests drive.readonly for listing and drive.file for files it creates or opens—not unrestricted full-Drive access.

Token and connection lifecycle

User-facing routes