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

# API Key Flow

> How agents authenticate with Encrata using the API key flow. Login, create key, operate.

# API Key Flow

The API key flow is Encrata's primary authentication path for agents. The agent logs in with user credentials, creates a long-lived API key, and uses it for all subsequent requests. No human interaction required after initial setup.

## When to use it

* Your agent needs **autonomous, long-lived access** to Encrata's lookup APIs
* You want **zero-friction operation** - authenticate once, operate indefinitely
* Your agent runs on any platform - MCP servers, custom scripts, LLM integrations, orchestration frameworks

## How it works

```mermaid theme={"dark"}
sequenceDiagram
    participant Agent
    participant Encrata

    Agent->>Encrata: POST /api/auth/login (email + password)
    Encrata-->>Agent: 200 OK (session token)
    Agent->>Encrata: POST /api/keys (name: "agent-key")
    Encrata-->>Agent: 200 OK (API key: enc_live_xxx...)
    Agent->>Encrata: POST /api/agent/lookup (Bearer enc_live_xxx...)
    Encrata-->>Agent: 200 OK (enrichment data)
```

1. Agent hits the login endpoint with user credentials
2. Encrata returns a session token
3. Agent creates a named API key using the session token
4. Agent uses the API key as a Bearer token for all subsequent calls
5. API key doesn't expire agent operates indefinitely until revoked

## Step 1: Authenticate

```http theme={"dark"}
POST https://encrata.com/api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}
```

**Success response:**

```json theme={"dark"}
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_...",
    "email": "user@example.com"
  }
}
```

## Step 2: Create an API key

```http theme={"dark"}
POST https://encrata.com/api/keys
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "name": "my-agent-key"
}
```

**Success response:**

```json theme={"dark"}
{
  "key": "enc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "my-agent-key",
  "created_at": "2026-05-26T10:00:00Z"
}
```

<Warning>
  The API key is returned exactly once. Store it securely it cannot be retrieved again.
</Warning>

## Step 3: Operate

Use the API key as a Bearer token on every request:

```http theme={"dark"}
POST https://encrata.com/api/agent/lookup
Authorization: Bearer enc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "email": "target@example.com"
}
```

## What you get

* **Immediate access** - no approval workflow, no waiting
* **All endpoints** - email, phone, IP, domain, company, Google, dark web, username
* **Credit-based** - each lookup deducts from your balance
* **No expiration** - keys stay valid until explicitly revoked

## Credential lifecycle

| Event                       | What happens                   |
| --------------------------- | ------------------------------ |
| Key created                 | Active immediately, full scope |
| Credits exhausted           | 402 responses until topped up  |
| Key revoked (dashboard/API) | 401 on all subsequent requests |
| Account suspended           | All keys invalidated           |

## Errors

| Code  | Error                             | Agent action                     |
| ----- | --------------------------------- | -------------------------------- |
| `401` | Invalid credentials / expired key | Re-authenticate or alert user    |
| `402` | Insufficient credits              | Check balance, notify user       |
| `429` | Rate limited                      | Retry after `Retry-After` header |
| `422` | Invalid request body              | Fix request format               |

## Security considerations

* **Store keys securely** treat API keys as secrets, never commit to source control
* **Use named keys** create descriptive names so users can identify and revoke agent keys
* **Monitor usage** agents should check credits periodically to avoid unexpected failures
* **Handle revocation gracefully** if a 401 is received on a previously-working key, the agent should notify the user rather than attempting to re-create keys