For Developers

How to configure your AI agent to use Encrata’s auth.md for autonomous authentication.

For developers

This guide shows you how to point your AI agent at Encrata’s auth.md and configure it for autonomous operation. Whether you’re building a custom agent, using an orchestration framework, or configuring an AI coding tool, the setup is the same.

Quick start

1. Get an API key from encrata.com/api-keys
2. Point your agent at https://encrata.com/auth.md
3. Provide the API key to your agent’s configuration

That’s it. The agent reads the file and knows how to call every endpoint.

Option A: Provide the API key directly

If you already have an API key, just configure your agent with it:

# Python agent example
import requests

API_KEY = "enc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.post(
    "https://encrata.com/api/agent/lookup",
    headers=headers,
    json={"email": "[e-mail]"}
)

Option B: Let the agent authenticate

Point your agent at auth.md and provide credentials. The agent will:

1. Fetch https://encrata.com/auth.md
2. Parse the authentication steps
3. Login with your credentials
4. Create a named API key
5. Use the key for all subsequent operations

System prompt example

You have access to Encrata's OSINT API. Read https://encrata.com/auth.md 
for authentication instructions. Use the API key: enc_live_xxx...

Available endpoints:
- POST /api/agent/lookup - email enrichment
- POST /api/agent/phone - phone lookup  
- POST /api/agent/ip - IP intelligence
- POST /api/agent/domain - domain info
- POST /api/agent/company - company search
- POST /api/agent/google - web search
- POST /api/agent/darkweb - dark web search
- POST /api/agent/username - username search

Option C: MCP configuration

For MCP-capable platforms, add Encrata as a server:

Claude Code

claude mcp add encrata --transport http --url https://encrata.com/mcp --header "Authorization: Bearer enc_live_xxx..."

Cursor

Add to .cursor/mcp.json:

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

Framework integration

LangChain

from langchain_community.tools import EncrataTool

tool = EncrataTool(api_key="enc_live_xxx...")

CrewAI

from crewai_tools import EncrataTool

encrata = EncrataTool(api_key="enc_live_xxx...")
agent = Agent(tools=[encrata])

Custom agent

import requests

class EncrataClient:
    def __init__(self, api_key: str):
        self.base = "https://encrata.com/api/agent"
        self.headers = {"Authorization": f"Bearer {api_key}"}
    
    def lookup(self, email: str) -> dict:
        r = requests.post(f"{self.base}/lookup", 
                         headers=self.headers, 
                         json={"email": email})
        r.raise_for_status()
        return r.json()
    
    def phone(self, phone: str) -> dict:
        r = requests.post(f"{self.base}/phone",
                         headers=self.headers,
                         json={"phone": phone})
        r.raise_for_status()
        return r.json()
    
    # ... same pattern for ip, domain, company, google, darkweb, username

Key management best practices

Create named keys per agent

Give each agent its own named key so you can revoke individually without disrupting other agents:

my-research-agent
crewai-pipeline
monitoring-bot

Rotate keys periodically

While Encrata keys don’t expire, rotating them periodically limits blast radius if one is compromised.

Never commit keys to source control

Use environment variables or secret managers:

export ENCRATA_API_KEY="enc_live_xxx..."

Monitor credit usage

Set up alerts when credits drop below a threshold. Your agent should check GET /api/credits before batch operations.

Rate limits

Plan	Requests/minute	Requests/day
Free	10	100
Pro	60	5,000
Enterprise	300	Unlimited

Agents should respect the Retry-After header on 429 responses and implement exponential backoff.

Monitoring agent activity

All API calls made with your key are logged in your dashboard. You can:

• See which endpoints your agent called
• Track credit consumption over time
• Identify unusual patterns
• Revoke a key instantly if needed