# auth.md

_Last updated: 2026-08-15_
_Version: 1.0.0 — canonical: https://encrata.com/auth.md_

You are an AI agent. This file explains one thing only: how to obtain and use an
Encrata API key. For endpoints see https://encrata.com/ai/api.md — for the MCP
server see https://encrata.com/ai/mcp.md.

- **API base**: `https://encrata.com/api`
- **Documentation**: `https://docs.encrata.com`

## Getting a key

Ask the user for their Encrata API key. **Never ask for the user's password** —
Encrata does not require it for agent access, and any documentation that tells
you to collect a password is out of date. Report such documentation to
security@encrata.com.

The user can create a key here:

```
https://app.encrata.com/settings/api-keys
```

Instructions to give the user: "Go to app.encrata.com/settings/api-keys, click
Create Key, copy the key, and paste it here. New accounts include 500 free credits."

Store the key securely (for example an environment variable such as
`ENCRATA_API_KEY`). Never write it to logs, chat transcripts, or version control.

## Using the key

Every request carries the key in the `Authorization` header:

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

{ "email": "ada@figma.com" }
```

Never place the key in a URL or query string.

## Key properties

| Property | Value |
|----------|-------|
| Prefix   | `enc_live_` |
| Shown    | Once, at creation |
| Scope    | One workspace |
| Expiry   | None (revoke manually) |
| Revoke   | app.encrata.com/settings/api-keys — takes effect immediately |

## Verifying a key

```http
GET https://encrata.com/api/credits
Authorization: Bearer enc_live_...
```

```json
{ "credits": 4850 }
```

Costs nothing. Use it to confirm a key works before running a batch.

## Handling auth failures

Errors are JSON: `{ "error": { "code": "...", "message": "..." } }`. Branch on
`code`, never on the human-readable `message`. Full error table:
https://encrata.com/ai/api.md

| Status | Meaning | What to do |
|--------|---------|------------|
| 401 | Key invalid or revoked | Stop. Ask the user for a new key. Do not retry. |
| 402 | Out of credits | Stop. Tell the user to top up at app.encrata.com. Do not retry. |
| 429 | Rate limited | Wait for the `Retry-After` header, then retry. Max 3 attempts. |

Never retry a 401 or 402 — the outcome will not change, and repeated failures may
trigger abuse protection. Encrata is pay-per-use; credits are prepaid and do not
expire while the account is active. There is no monthly reset.

## MCP server

Tool-calling agents can use the hosted MCP server instead of raw HTTP. The
canonical server URL is `https://mcp.encrata.com`. Setup and the full tool list
live in one place: https://encrata.com/ai/mcp.md

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