The auth.md File

auth.md is a single Markdown file that Encrata publishes to tell agents how to authenticate. This page covers where to find it, the sections it contains, and how agents are expected to parse it.

Where to find it

The file is served from the API host:

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

Agents discover it by:

Reading documentation or SDK pointers
Fetching the canonical URL directly
Following links from AI tool configurations (Cursor, Claude Code, Windsurf)

The file carries a Last updated date and its canonical URL at the top, so an agent can tell whether a cached copy is stale.

Sections in order

The file is a numbered walkthrough an agent follows top to bottom.

Title and summary table

A one-line title (# auth.md), a short preamble addressed to the agent, and a table of the facts an agent needs before anything else:


API base URL	`https://developer.encrata.com`
Auth header	`Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
Key format	`enc_` followed by 32 hex characters
Docs index	`https://docs.encrata.com/llms.txt`
Endpoint list	`https://docs.encrata.com/api-reference/overview`

The file doesn’t list every endpoint. It points agents to the docs index and the endpoint list instead.

1. Get a key

Tells the agent to ask the user for their API key. The user signs in at https://app.encrata.com, opens API Keys, clicks Create API key, and pastes the key (it starts with enc_). The agent must never ask for the user’s password or sign in on the user’s behalf. Encrata has no password-login endpoint for agents. The agent stores the key in an environment variable such as ENCRATA_API_KEY, and never writes it to logs, chat transcripts, URLs, or version control.

2. Use the key

Shows the key sent as a Bearer token on every request:

POST https://developer.encrata.com/api/lookup/email/validity
Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "email": "satya@microsoft.com" }

The key never goes in a query string.

3. Verify the key

Before running a batch, the agent confirms the key works with a free call:

GET https://developer.encrata.com/api/account/credits
Authorization: Bearer enc_...

{
  "credits_remaining": 4850,
  "credits_used": 150,
  "stats_degraded": false,
  "total_lookups": 120
}

A 200 means the key is valid. credits_remaining is the account balance.

4. Key facts

Property	Value
Scope	One workspace. All keys in the account share its credits and rate limit.
Expiry	None. A key works until it is disabled or revoked.
Credit cap	Optional per key. Once reached, requests return `402`.
Read again	`GET /api/account/keys/reveal?id={id}` while the key’s `revealable` is `true`. Requires a non-readonly role.
Revoke	Dashboard, or `DELETE /api/account/keys?id={id}`. Add `&permanent=true` to delete a leaked key for good.

5. Errors

Errors are JSON. On authentication and rate-limit failures the body looks like this:

{
  "success": false,
  "result": { "code": "unauthorized" },
  "message": "Please sign in to continue.",
  "request_id": "050916e6-f499-4113-934d-d92d07aa1150"
}

Agents branch on the HTTP status, then on result.code, and never on message. They include request_id when reporting a problem. See Errors for the full list.

Status	`result.code`	Meaning	What to do
`401`	`unauthorized`	Key missing, invalid, disabled, or revoked	Stop. Ask the user for a new key. Do not retry.
`402`	`insufficient_credits`	Account is out of credits, or the key hit its credit cap	Stop. Tell the user to add credits or raise the key’s cap. Do not retry.
`403`	`forbidden`	Key is valid but the user’s workspace role can’t do this	Stop. Tell the user which action needs a higher role.
`429`	`rate_limited`	Rate limit reached	Wait for `X-Ratelimit-Reset` seconds, then retry. Max 3 attempts.
`5xx`	`internal` / `upstream_unavailable`	Server or upstream provider error	Retry with exponential backoff (1s, 2s, 4s). Max 3 attempts.

6. Rate limits

200 requests per minute per account, shared by every key.
Every API response includes:
- X-Ratelimit-Limit: the limit (200)
- X-Ratelimit-Remaining: requests left in the current window
- X-Ratelimit-Reset: seconds until the window resets (not a timestamp)
429 responses don’t include a Retry-After header. Use X-Ratelimit-Reset.

7. Rules for agents

Use only https://developer.encrata.com. encrata.com and app.encrata.com are the website and dashboard, not the API.
Never request, store, or send the user’s password.
Keep the key out of URLs, logs, and anything echoed back to the user.
Verify the key with /api/account/credits before spending credits.
Stop on 401, 402, and 403. Back off on 429 and 5xx.

How agents parse it

Agents treat auth.md as both prose and structured data:

Read the summary table first to learn the host, header, and key format
Follow the numbered steps in order: get a key, use it, verify it
Extract code blocks as templates for HTTP requests. Fenced blocks with language hints (http, json) let agents identify request shapes without ambiguity
Branch on status and result.code using the errors table
Follow the docs index to find endpoints beyond the examples

Keep the file short and high in signal. Anything an agent doesn’t need to authenticate belongs in the main documentation, not in auth.md.

Account & team

Run your integration

Use cases

Integrations

AI tools

auth.md

The auth.md File

Where to find it

Sections in order

Title and summary table

1. Get a key

2. Use the key

3. Verify the key

4. Key facts

5. Errors

6. Rate limits

7. Rules for agents

How agents parse it

​Where to find it

​Sections in order

​Title and summary table

​1. Get a key

​2. Use the key

​3. Verify the key

​4. Key facts

​5. Errors

​6. Rate limits

​7. Rules for agents

​How agents parse it

Where to find it

Sections in order

Title and summary table

1. Get a key

2. Use the key

3. Verify the key

4. Key facts

5. Errors

6. Rate limits

7. Rules for agents

How agents parse it