> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encrata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```http theme={"dark"}
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:

```http theme={"dark"}
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:

```http theme={"dark"}
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:

```json theme={"dark"}
{
  "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`.