API Key Flow

The API key flow gives an agent long-lived access without sharing the user’s Encrata password.

When to use it

Your agent needs long-lived access to Encrata’s lookup APIs.
You want each agent or service to use a separately named key.
You need to disable or delete one agent’s access without affecting other integrations.

How it works

The user creates an API key in the dashboard.
The user provides the key to the agent through a secure configuration channel.
The agent sends the key as a Bearer credential on each request.

Never ask a user for their Encrata password.

Step 1: Create a key

Sign in to the Encrata dashboard, open API Keys, and click Create API key. Copy the key and give it to the agent. If you already have a valid API key, you can create another one programmatically:

POST https://developer.encrata.com/api/account/keys
Authorization: Bearer enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

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

The returned key uses the format enc_ followed by 32 hexadecimal characters.

Step 2: Configure the agent

Store the key in an environment variable such as ENCRATA_API_KEY, or in a secret manager. Never write it to logs, chat transcripts, URLs, or version control.

Step 3: Verify the key

Before running a batch, confirm the key works. This call is free.

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

{
  "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.

Step 4: Make API calls

Send the key as a Bearer token on every request. Never put it in a query string.

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

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

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.

Credential lifecycle

Event	What happens
Key created	The key is active immediately
Credits exhausted or cap reached	Requests that require credits return `402`
Role too low for an action	The request returns `403`
Key disabled or revoked	Requests with the key return `401`
Key permanently deleted	The key record is removed

Security considerations

Store keys in an environment variable or secret manager.
Create a separately named key for each agent.
Set a credit limit to cap the key’s spend.
Permanently delete a compromised key with DELETE /api/account/keys?id={id}&permanent=true.

Account & team

Run your integration

Use cases

Integrations

AI tools

auth.md

When to use it

How it works

Step 1: Create a key

Step 2: Configure the agent

Step 3: Verify the key

Step 4: Make API calls

Key facts

Credential lifecycle

Security considerations

​When to use it

​How it works

​Step 1: Create a key

​Step 2: Configure the agent

​Step 3: Verify the key

​Step 4: Make API calls

​Key facts

​Credential lifecycle

​Security considerations

When to use it

How it works

Step 1: Create a key

Step 2: Configure the agent

Step 3: Verify the key

Step 4: Make API calls

Key facts

Credential lifecycle

Security considerations