The auth.md File

Anatomy of Encrata’s auth.md. Where it lives, what it contains, and how agents parse it.

The auth.md file

auth.md is a single Markdown file Encrata publishes at a well-known location to tell agents how to authenticate. This page walks through where to find it, the sections it contains, and how agents are expected to parse it.

Where to find it

The file is served at the domain root:

https://encrata.com/auth.md

Agents discover it by:

• Reading documentation or SDK pointers
• Fetching the well-known URL directly
• Following links from AI tool configurations (Cursor, Claude Code, Windsurf)

Sections in order

A well-formed Encrata auth.md is organized as a numbered walkthrough an agent follows top to bottom:

Title and intro

A one-line title (# auth.md) followed by a short preamble addressed to the agent. States that Encrata supports API key authentication for agentic access and names the real hostnames:

• Resource server: https://encrata.com
• API base: https://encrata.com/api
• Documentation: https://docs.encrata.com

Step 1: Get credentials

Shows the agent how to authenticate:

POST https://encrata.com/api/auth/login
Content-Type: application/json

{
  "email": "[e-mail]",
  "password": "password"
}

Documents the response shape including the session token returned.

Step 2: Create an API key

Shows the agent how to programmatically create a long-lived API key:

POST https://encrata.com/api/keys
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "name": "agent-key"
}

Documents the API key format: enc_live_ prefix followed by 32 characters.

Step 3: Use the credential

Shows that the API key is presented as a Bearer token:

Authorization: Bearer enc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 4: Available endpoints

Lists every endpoint the agent can call with the API key:

Endpoint	Description
POST /api/agent/lookup	Email enrichment
POST /api/agent/phone	Phone number lookup
POST /api/agent/ip	IP intelligence
POST /api/agent/domain	Domain search
POST /api/agent/company	Company search
POST /api/agent/google	Google search
POST /api/agent/darkweb	Dark web search
POST /api/agent/username	Username search
GET /api/credits	Check remaining credits

Step 5: Credits

Documents the credit system. Each lookup costs credits, and the agent can check its balance before making calls.

Step 6: MCP configuration

Provides the MCP server config for agents that support the Model Context Protocol:

{
  "mcpServers": {
    "encrata": {
      "url": "https://encrata.com/mcp",
      "headers": {
        "Authorization": "Bearer enc_live_xxxx..."
      }
    }
  }
}

Step 7: Errors

Documents error codes the agent should handle:

Code	Meaning	Action
401	Invalid or expired key	Re-authenticate
402	Insufficient credits	Check balance, alert user
429	Rate limited	Retry after delay
500	Server error	Retry with backoff

Step 8: Rate limits

Documents the rate limiting policy so agents can self-throttle.

Step 9: Revocation

Documents that API keys can be revoked via the dashboard or API, and agents should handle 401 responses by re-authenticating.

How agents parse it

Agents treat auth.md as both prose and structured data:

• Scan headings to find sections relevant to the current step (authentication vs. operation)
• Read Step 1 first to learn how to authenticate before attempting any API calls
• Extract code blocks as templates for HTTP requests. Fenced blocks with language hints (http, json) let agents identify request shapes without ambiguity
• Use the endpoint table to understand available capabilities
• Check credits before making expensive calls

Keep the file conservative in length and high in signal. Anything an agent doesn’t need to authenticate or operate against the API belongs in the main documentation, not in auth.md.