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": "user@example.com",
  "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.

Overview

Configuration

auth.md

The auth.md File

The auth.md file

Where to find it

Sections in order

Title and intro

Step 1: Get credentials

Step 2: Create an API key

Step 3: Use the credential

Step 4: Available endpoints

Step 5: Credits

Step 6: MCP configuration

Step 7: Errors

Step 8: Rate limits

Step 9: Revocation

How agents parse it

​The auth.md file

​Where to find it

​Sections in order

​Title and intro

​Step 1: Get credentials

​Step 2: Create an API key

​Step 3: Use the credential

​Step 4: Available endpoints

​Step 5: Credits

​Step 6: MCP configuration

​Step 7: Errors

​Step 8: Rate limits

​Step 9: Revocation

​How agents parse it

The auth.md file

Where to find it

Sections in order

Title and intro

Step 1: Get credentials

Step 2: Create an API key

Step 3: Use the credential

Step 4: Available endpoints

Step 5: Credits

Step 6: MCP configuration

Step 7: Errors

Step 8: Rate limits

Step 9: Revocation

How agents parse it