Skip to content
User Guide
Settings
API Keys

API Keys

API keys authenticate requests to the Evident REST API. Each request sends the key in the X-API-Key header:

X-API-Key: ipid_<64-hex-chars>

Keys are per-tenant and grant full ingestion and lookup access to your workspace. Treat them like a database password.

Where to find them

Sign in to your Evident dashboard and open Settings → API Keys. The page lists your active keys and provides a Generate Key button.

Generating a new key

  1. Click Generate Key.
  2. A dialog appears with your new key, prefixed ipid_, followed by 64 hex characters.
  3. Copy it immediately. The dialog is the only time the raw key is ever visible — Evident stores only a SHA-256 hash on the server and cannot recover the original value later. If you dismiss the dialog without copying, you must generate a new key.
  4. Paste the key into your secret manager (1Password, AWS Secrets Manager, Vercel env vars, GitHub Actions secrets — wherever your application reads it from).
  5. Click I’ve saved my key to close the dialog.

The new key is active immediately. Requests using it authenticate against your workspace within seconds.

The key prefix

After creation, the API Keys list displays each key by its prefix — the first 12 characters of the raw value, followed by a fixed number of • characters:

ipid_abc1234••••••••

The prefix is safe to display, log, or copy — on its own it cannot authenticate a request. Use it to identify which key an application is using without exposing the credential.

Revoking a key

  1. On the API Keys list, click the trash icon next to the key you want to revoke.
  2. Confirm the revocation in the dialog.
  3. The key is revoked immediately on the server. Requests using the revoked key will start returning 401 Unauthorized within seconds.

Revocation is permanent — a revoked key cannot be re-enabled. If you need to restore access, generate a new key and update the application that was using the old one.

Recovery

There is no way to recover the raw value of a key after the create-time dialog closes. If you lose a key:

  1. Generate a new one.
  2. Update the application(s) that were using the lost key to use the new value.
  3. Revoke the lost key. Even though you can’t produce it to authenticate, it may still be sitting in a compromised environment; revoking it removes any remaining risk.

How keys are stored

Evident stores only the SHA-256 hash of each raw key, plus the 12-character prefix for display. The raw key is not persisted anywhere on the server after creation.

This means:

  • A database breach cannot leak your working credentials.
  • Evident support cannot look up your key even if you ask — the raw value doesn’t exist in our systems.
  • Rotating a key requires a full replacement in the application using it — you can’t “reset” a key back to a previous value.

Security best practices

Server-side only. Read the key from an environment variable or secret manager on your server. Never bake it into client-side JavaScript, mobile app bundles, or public repositories.

No NEXT_PUBLIC_* prefixes. In a Next.js project, any variable prefixed NEXT_PUBLIC_* is inlined into the client bundle and visible to every visitor. Use a plain EVIDENT_API_KEY (or similar) that stays server-side. The same rule applies to REACT_APP_* in Create React App or VITE_* in Vite projects — anything the framework treats as browser-visible is not safe for credentials.

One key per environment. Generate a distinct key for each deployment (development, staging, production). Revoking a staging key should never take down production.

One key per service (optional but useful). If two independent applications need the API, generate a key per service. When one leaks or needs to rotate, you only touch that service.

Rotate regularly. For long-lived deployments, rotate keys on a schedule (quarterly is common). Generate the new key, deploy it to the service, then revoke the old one after confirming the new one is in use.

Watch the last_used timestamp. The API Keys list shows when each key was last used. A key that hasn’t been used for weeks is probably safe to revoke — dead credentials are attack surface.

Using a key

Pass the raw key in the X-API-Key header on every request:

curl https://api.useevident.com/v1/lookup \
  -H "X-API-Key: ipid_abc1234..." \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.42"}'

See the REST API reference for the full endpoint contract, and the Next.js integration guide for a production-ready pattern that reads the key from an environment variable.

Common questions

How many keys can I have? There is no hard limit. Generate as many as you need for per-service or per-environment separation.

Can I see when a key was last used? Yes. The list view shows the last_used timestamp for each active key.

A key I revoked is still working. Why? Revocation propagates within about a minute — Evident caches the active-key set in-memory for up to 60 seconds. After that window, the revoked key will consistently return 401 Unauthorized.

Can I rename a key? Not currently. Keys are identified by their prefix. For clarity, use the prefix as an identifier when documenting which application uses which key.

Can I set an expiration date on a key? Not currently. Rotate manually on your own schedule.

Quotas