For AI Agents

How AI agents discover, authenticate, and operate with Encrata using auth.md.

For AI agents

This guide is for AI agents (LLM-based systems that need to autonomously authenticate with and use Encrata’s APIs). If you’re a developer configuring an agent, see For Developers.

Discovery

Fetch the auth file from Encrata’s domain:

GET https://encrata.com/auth.md

The file contains everything needed to authenticate and operate. Parse it once at startup and cache locally. It changes only on API updates.

Minimum steps to operate

1. Authenticate

If you have an API key (format: enc_live_ + 32 chars), skip to step 3.

If you have user credentials:

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

{
  "email": "<user_email>",
  "password": "<user_password>"
}

2. Create an API key

Use the session token from step 1:

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

{
  "name": "<descriptive_name>"
}

Store the returned key value securely. It’s shown exactly once.

3. Make API calls

Use the API key as a Bearer token:

POST https://encrata.com/api/agent/lookup
Authorization: Bearer enc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

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

Available endpoints

Endpoint	Method	Body	Description
/api/agent/lookup	POST	{ "email": "..." }	Full email enrichment
/api/agent/phone	POST	{ "phone": "..." }	Phone number lookup
/api/agent/ip	POST	{ "ip": "..." }	IP geolocation & threat intel
/api/agent/domain	POST	{ "domain": "..." }	Domain information
/api/agent/company	POST	{ "company": "..." }	Company search
/api/agent/google	POST	{ "query": "..." }	Google search results
/api/agent/darkweb	POST	{ "query": "..." }	Dark web mentions
/api/agent/username	POST	{ "username": "..." }	Username across platforms
/api/credits	GET	none	Check remaining credits

Credit system

Every lookup costs credits:

• Check balance before expensive operations: GET /api/credits
• Handle 402 responses gracefully. Alert the user that credits are exhausted
• Don’t retry on 402. The operation won’t succeed without a top-up

Error handling

401 → Key invalid or revoked. Re-authenticate.
402 → No credits. Alert user.
429 → Rate limited. Wait for Retry-After header value, then retry.
422 → Bad request. Fix the request body.
500 → Server error. Retry with exponential backoff (max 3 attempts).

MCP alternative

If your platform supports MCP, you can skip HTTP entirely:

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

Tools available: lookup_email, lookup_phone, lookup_ip, lookup_domain, lookup_company, google_search, darkweb_search, username_search, check_credits.

Behavioral guidelines

• Be efficient - batch related lookups when possible rather than making many sequential calls
• Respect rate limits - self-throttle to avoid 429 responses
• Cache results - enrichment data doesn’t change frequently, cache for at least 1 hour
• Check credits proactively - before starting a batch of lookups, verify sufficient balance
• Handle failures gracefully - never crash on API errors, always have a fallback response for the user

Revocation

API keys can be revoked at any time by the user via their dashboard or the API. If you receive a 401 on a previously-working key:

1. Do not attempt to create a new key automatically
2. Inform the user that access has been revoked
3. Wait for the user to provide a new key or re-authorize