Authentication

EchoSift supports two authentication modes depending on how you access the platform.

---

OAuth 2.1 PKCE (for MCP clients)

OAuth is the recommended mode for MCP clients (Claude Code, Cursor, Codex). No manual key management needed.

How it works

1. Your MCP client points at https://mcp.echosift.io/mcp.
2. On first connect, the client discovers the authorization server from:

   GET https://mcp.echosift.io/.well-known/oauth-authorization-server

3. Your browser opens to the EchoSift login page.
4. You sign in with your EchoSift email (magic link). Same email as your echosift.io account.
5. You approve the authorization. The client receives an access token.
6. The token is stored locally and auto-refreshed on expiry.

No config files, no secrets to manage. The flow is identical to how Stripe’s developer tools work.

Scope

OAuth tokens grant the same read-only access as API keys. They cannot generate briefs or access admin endpoints.

Pro requirement

OAuth login and API key creation both require a Pro subscription. If you are on the free plan, upgrade at echosift.io/billing.

---

API keys (es_*)

API keys are the fallback for MCP clients without OAuth support, and the primary auth mode for direct REST API calls.

Format

Keys follow the pattern:

es_<prefix>_<secret>

Example: es_prod_AbCdEfGhIj1234567890XyZ

The prefix is short (8 chars), human-readable, and used to identify the key in logs and the Integrations UI. The secret portion is not stored by EchoSift; only a SHA-256 hash is kept server-side.

Creating a key

1. Log in to echosift.io.
2. Go to Settings > Integrations.
3. Click Create API key.
4. Give the key a name (for example, the tool or service that will use it).
5. Copy the full key. It is shown only once. Store it immediately in your secret manager.

Using a key

Pass it as a Bearer token in every request:

curl https://api.echosift.io/api/dashboard/overview \
  -H "Authorization: Bearer es_YOUR_KEY_HERE"

In MCP client configs:

{
  "headers": {
    "Authorization": "Bearer es_YOUR_KEY_HERE"
  }
}

Revoking a key

Go to Settings > Integrations and click the delete icon next to the key. Revocation is immediate.

Security properties

• Keys are hashed with SHA-256 before storage. EchoSift cannot recover a raw key after creation.
• Keys carry read-only scope (ROLE_API_CLIENT). They cannot mutate any state.
• Each API call with a key is metered (best-effort) for usage tracking.
• Last-used timestamp is updated on each call.

---

Comparison

	OAuth 2.1 PKCE	API key
Storage	Client-managed, auto-refreshed	Your secret manager
Setup	Browser flow (one-time)	Create in Settings
Best for	MCP clients with OAuth support	REST API, clients without OAuth
Revocation	Sign out or re-authorize	Settings > Integrations