Authentication

API keys, OAuth tokens, and how to authenticate requests to the edgar.tools API.

Overview

edgar.tools supports three authentication methods depending on how you access the platform:

For most developers integrating with the REST API, you only need an API key.

API Key Authentication

API keys authenticate requests to the REST API at https://api.edgar.tools/v1/*. Every API request (except /v1/health and /v1/stats) requires a valid key.

Key format

API keys use the prefix etk_ (edgar tools key) followed by URL-safe characters:

etk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Sending your key

Include your API key in the request header. Both formats are accepted:

# Option 1: Authorization header (recommended)
curl -H "Authorization: Bearer etk_your_key_here" \
  https://api.edgar.tools/v1/search?q=Apple

# Option 2: X-API-Key header
curl -H "X-API-Key: etk_your_key_here" \
  https://api.edgar.tools/v1/search?q=Apple

Getting an API key

1. Sign up at edgar.tools/signup with Google. Free accounts include one API key.
2. Go to Settings → API Keys and click Create API Key.
3. Copy and store the key — it's shown only once.

Store your key safely. Your API key is shown only at creation time. We store a hash, not the key itself. If you lose your key, revoke it and create a new one.

Tier model

Each authenticated request carries a tier. Higher tiers unlock additional endpoints:

When your tier is insufficient for an endpoint, the API returns 403 Insufficient tier with the required tier in the response body.

For the full endpoint matrix, see the API Reference.

MCP Authentication

The MCP (Model Context Protocol) server uses OAuth Bearer tokens, not API keys. MCP authentication is handled automatically by your AI client (Claude Desktop, Claude Code, etc.) — when you connect Claude to edgar.tools via MCP, the OAuth flow runs in your browser. Once authorized, your AI client receives a token and uses it transparently for all tool calls.

MCP vs API keys. MCP uses a separate OAuth token flow. Do not use API keys (etk_...) for MCP connections. See the MCP Setup guide for connection instructions and MCP Tiers for which tools each tier exposes.

Authentication errors

The API returns standard HTTP status codes for authentication failures:

Example 401 response:

{
  "error": "Authentication required",
  "message": "Valid API key required. Use 'Authorization: Bearer etk_...' header."
}

Example 403 response:

{
  "error": "Insufficient tier",
  "message": "Requires professional or higher",
  "your_tier": "free"
}

See Errors & Limits for full error handling guidance.

Security best practices

• Never commit keys to source control. Use environment variables or a secrets manager.
• Use separate keys per environment. Create distinct keys for development, staging, and production.
• Rotate keys regularly. Revoke old keys from your settings page and generate new ones.
• Keep keys server-side. Never expose API keys in client-side JavaScript or mobile apps.

# Store your key in an environment variable
export EDGAR_API_KEY="etk_your_key_here"

import os
api_key = os.environ["EDGAR_API_KEY"]

To summarize

• Use API keys (etk_...) for REST API requests via the Authorization header.
• Tier gating: Free / Professional / Analyst / Enterprise. Each endpoint declares its minimum tier.
• MCP connections use OAuth tokens, not API keys.
• Store keys in environment variables and never commit them to source control.