API keys & authentication

Encrata API keys

API keys are secret credentials used to authenticate your requests. They are unique to your account and must be kept confidential. Every key starts with enc_. You need at least one key to call the Encrata API from code, the CLI, or an AI tool.

Create an API key

Choose the method that fits your workflow.

Dashboard
Encrata API
CLI

Open the Encrata dashboard.

Open the API Keys page

Click Create API key

Name your key

Choose a name that identifies where the key is used, for example production-backend.

Copy and store the key

Copy the enc_ key and store it in a secret manager before closing the dialog.

Use POST /api/account/keys to create another key programmatically. The key you use to authenticate must belong to a workspace member with permission to manage keys.

curl -X POST https://developer.encrata.com/api/account/keys \
  -H "Authorization: Bearer enc_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-backend"}'

The response includes the new key in the key field. Store it in a secret manager as soon as you receive it.

Install the Encrata CLI, sign in with an existing key, then create a named key:

encrata login enc_xxxxxxxx
encrata keys create production-backend

Copy the new enc_ key from the command output and store it in a secret manager.

Revealable keys can be read again with GET /api/account/keys/reveal. Access is limited by workspace permissions.

Use the API key in your code

Authenticate every request by sending your key as a Bearer credential in the Authorization header.

Store the key as an environment variable

Keep the key out of your source code. In a Node.js project, store it in a .env file at the project root:

.env

ENCRATA_API_KEY=enc_xxxxxxxx

Add .env to your .gitignore so the key is never committed.

.gitignore

.env

Send the key in the Authorization header

Read the key from the environment and pass it on every call:

curl -X POST https://developer.encrata.com/api/lookup/email/validity \
  -H "Authorization: Bearer enc_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "satya@microsoft.com"}'

import os, requests

resp = requests.post(
    "https://developer.encrata.com/api/lookup/email/validity",
    headers={"Authorization": f"Bearer {os.environ['ENCRATA_API_KEY']}"},
    json={"email": "satya@microsoft.com"},
)

const resp = await fetch("https://developer.encrata.com/api/lookup/email/validity", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ENCRATA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "satya@microsoft.com" }),
});

Key behavior

Behavior	Detail
Format	`enc_` followed by 32 hexadecimal characters
Scope	Tied to your user account
Credit limit	Optional per-key spend cap - `402` once reached
Removal	Permanently delete a compromised key with `DELETE /api/account/keys?id={id}&permanent=true`
Usage tracking	Every request is logged with credits consumed and response time

Set a credit limit

Every key can carry a credit limit: a cap on how many credits it is allowed to spend. A key with no limit can spend your full account balance, so a leaked or runaway key drains everything. A capped key stops at its ceiling instead, which contains the damage. Set a cap with POST /api/account/keys/limit:

curl -X POST https://developer.encrata.com/api/account/keys/limit \
  -H "Authorization: Bearer enc_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"id": "a1b2c3d4-0000-4000-8000-000000000000", "credit_limit": 5000}'

curl -X POST https://developer.encrata.com/api/account/keys/limit \
  -H "Authorization: Bearer enc_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"id": "a1b2c3d4-0000-4000-8000-000000000000", "credit_limit": null}'

When a key reaches its limit, requests are rejected with 402 api key credit limit exceeded. Raise the limit or use another key to continue.

Send credit_limit: null to remove the cap. Setting a limit requires a non-readonly role in the active workspace. The maximum value is 2147483647.

Manage your keys

Inspect, rename, pause, and retire keys from the dashboard or the API. A workspace admin can manage other members’ keys in the same workspace.

List keys

See every key with its usage, limit, and last-used time.

Rename a key

Update a key’s display name.

Enable or disable

Temporarily turn a key off without deleting it.

Revoke or delete

Permanently delete a leaked key or soft-disable an unused key.

Known issue: A revoked key can be enabled again with PATCH ?action=enable and revealed with GET /api/account/keys/reveal. Revoked and disabled keys both appear as is_active: false. Permanently delete a leaked key.

Handle common errors

Email API errors use this shape:

{
  "error": "Invalid email address",
  "code": "bad_request"
}

Status	`code` or error	When it happens	What to do
`400`	`bad_request`	The JSON body is invalid or `email` is not a valid address.	Send valid JSON with an `email` field.
`401`	`unauthorized`	The Encrata API key is missing, malformed, invalid, or revoked.	Send an active `enc_` key in the `Authorization` header.
`402`	`insufficient_credits`	Your account does not have enough credits for the lookup.	Add credits, then retry.
`402`	`api key credit limit exceeded`	The key has reached its configured credit limit.	Raise the key limit or use another permitted key.
`405`	`method_not_allowed`	The endpoint was called with a method other than `POST`.	Send a `POST` request.
`413`	`payload_too_large`	The request body is larger than the endpoint accepts.	Send only the required request body.
`429`	`rate_limited`	You sent requests faster than the endpoint allows.	Wait before retrying; use exponential backoff.
`502`, `503`, `504`	`upstream_unavailable`	A required upstream provider is temporarily unavailable.	Retry with exponential backoff.
`500`	`internal`	An unexpected server error occurred.	Retry later; include the response request ID when contacting support.

Do not retry 400 or 401 responses unchanged. Correct the request or credential first. Retries are appropriate for 429 and 5xx responses.

Keep your API key secret. Do not commit it to version control or expose it in client-side code.

Overview

Configuration

Best practices

API keys & authentication

Encrata API keys

Create an API key

Use the API key in your code

Key behavior

Set a credit limit

Manage your keys

List keys

Rename a key

Enable or disable

Revoke or delete

Handle common errors

Next steps

Quickstart

All endpoints

​Encrata API keys

​Create an API key

​Use the API key in your code

​Key behavior

​Set a credit limit

​Manage your keys

List keys

Rename a key

Enable or disable

Revoke or delete

​Handle common errors

​Next steps

Quickstart

All endpoints

Encrata API keys

Create an API key

Use the API key in your code

Key behavior

Set a credit limit

Manage your keys

Handle common errors

Next steps