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

Create an API key in the dashboard, or create another with POST /api/account/keys using an existing key
Point your agent at https://developer.encrata.com/auth.md
Provide the API key to your agent’s configuration, for example as ENCRATA_API_KEY

The agent reads the file, verifies the key with the free GET /api/account/credits call, and follows the docs index to find endpoints.

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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.post(
    "https://developer.encrata.com/api/lookup/email/identity",
    headers=headers,
    json={"email": "target@example.com"}
)

Give the agent the API contract

Point your agent at auth.md and provide the API key through its secret or environment configuration. Never give the agent your Encrata password.

System prompt example

You have access to Encrata's data lookup API. Read https://developer.encrata.com/auth.md
for authentication instructions. Read the API key from ENCRATA_API_KEY.
Verify the key with GET /api/account/credits before running a batch.

Available endpoints:
- POST /api/lookup/email/identity - email enrichment

Framework integration

LangChain

from langchain_community.tools import EncrataTool

tool = EncrataTool(api_key="enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

CrewAI

from crewai_tools import EncrataTool

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

Custom agent

import requests

class EncrataClient:
    def __init__(self, api_key: str):
        self.base = "https://developer.encrata.com/api/lookup/email"
        self.headers = {"Authorization": f"Bearer {api_key}"}
    
    def lookup(self, email: str) -> dict:
        r = requests.post(f"{self.base}/identity", 
                         headers=self.headers, 
                         json={"email": email})
        r.raise_for_status()
        return r.json()

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

Encrata keys don’t expire. A key works until you disable or revoke it, so rotating periodically limits blast radius if one is compromised.

Set a credit cap per key

All keys share the account’s credits. Set an optional credit cap on each key so one agent can’t drain the balance. Once a key reaches its cap, its requests return 402.

Never commit keys to source control

Use environment variables or secret managers:

export ENCRATA_API_KEY="enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Monitor credit usage

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

Rate limits

Requests are limited to 200 per minute per account, shared by every key. Every response includes X-Ratelimit-Limit, X-Ratelimit-Remaining, and X-Ratelimit-Reset. On a 429, wait X-Ratelimit-Reset seconds, then retry, up to 3 attempts. 429 responses don’t include a Retry-After header. See Rate limits for the current limit, headers, and retry guidance.

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

Account & team

Run your integration

Use cases

Integrations

AI tools

auth.md

Quick start

Provide the API key directly

Give the agent the API contract

System prompt example

Framework integration

LangChain

CrewAI

Custom agent

Key management best practices

Rate limits

Monitoring agent activity

​Quick start

​Provide the API key directly

​Give the agent the API contract

​System prompt example

​Framework integration

​LangChain

​CrewAI

​Custom agent

​Key management best practices

​Rate limits

​Monitoring agent activity

Quick start

Provide the API key directly

Give the agent the API contract

System prompt example

Framework integration

LangChain

CrewAI

Custom agent

Key management best practices

Rate limits

Monitoring agent activity