Authentication

How EZType authenticates API calls — secret keys for backend code, public keys for browser code, and how access modes on each index control what's reachable.

EZType uses opaque API keys for all programmatic access. Two kinds, with distinct prefixes so they're impossible to confuse:

Prefix	Format	Use	Where to put it
`sk-ezt-`	`sk-ezt-<type>-<entropy><checksum>`	Full read + write	Backend code, env vars, secret managers — never in browser code
`pk-ezt-`	`pk-ezt-srh-<entropy><checksum>`	Read-only search	Browser code, mobile apps, embedded SDKs

Both go in the standard Authorization header:

bash

curl -H "Authorization: Bearer sk-ezt-pat-7Kx9mQ2vN8wL3pR5tY6uA1bC4dE8fG0hJ2kAbCd" \
  https://api.eztype.io/v1/search?serviceName=my-service&indexName=my-index&query=sw

Secret keys (`sk-ezt-`)

Server-side keys with full authority over your tenant's indexes. The <type> slot in the format encodes intended use:

pat — Personal Access Token. Created interactively by you in the dashboard. Use for one-off scripts, prototypes, your own server.
svc — Service account. Use for backend-to-backend integrations (your API server calling EZType, a CI pipeline running migrations, etc.).
adm — Admin key. Used internally for cluster operations and billing. You'll rarely need one as a customer.

All three carry equivalent server-side authority — the type is a label for your own organization. Every sk- key can read, write, delete, and manage versions on any index in your account.

Public keys (`pk-ezt-srh-`)

Read-only keys safe to embed in browsers, mobile apps, and any other client-side code. The worst-case impact of a leaked public key is anonymous search against your already-public data — which is exactly what pk-ezt-srh- keys are designed for.

A public key can only query indexes marked PUBLIC (see Access modes below). It cannot read records via lookupById against non-public indexes, cannot write, cannot delete, cannot manage versions.

Access modes

Each index has an access mode set when you create it (default API_KEY):

Mode	Anonymous	`sk-ezt-…`	`pk-ezt-srh-…`
PUBLIC	✓	✓	✓
API_KEY	✗	✓	search/lookup only

PUBLIC is the right mode for marketing data, demos, and anything you want indexable from anonymous traffic. API_KEY is the default for new indexes — fail-closed. You can change the mode on the dashboard's index detail page.

The four demo indexes (countries, words, addresses, doctors under the public eztype-demo service) are PUBLIC. That's what powers the homepage LiveDemo widget without anyone needing a key.

Format and checksums

Both formats end with a 4-character base62 checksum derived from the rest of the key. We validate it before any database lookup, so:

Mistyped or truncated keys return 401 immediately — no database round-trip on the error path.
Bots probing random strings get rejected at the format check, never reaching the lookup layer.

Customers integrating EZType in their own SDKs can use the same checksum routine to validate keys client-side — flagging copy-paste errors before making the first request.

Managing keys

Use the dashboard at /dashboard/api-keys (recommended) or the /v1/api-keys endpoints directly. Both paths support: create, list (metadata only — never plaintext), revoke.

A few rules baked into the API:

The plaintext key is returned exactly once at creation time. EZType stores only a SHA-256 hash; we cannot recover it later.
Keys cannot mint other keys — the /v1/api-keys endpoints accept only dashboard session auth (cookie). This keeps the audit trail clean.
Revocation is immediate and irreversible. To rotate a key, create the new one first, deploy the change, then revoke the old one.

What if I'm not using a key yet?

The homepage demo (/v1/search against the eztype-demo service) is fully anonymous — those indexes are PUBLIC. You can try the API without signing up.

Once you create your own service, your indexes default to API_KEY — queries fail without a key. Create one in the dashboard, set Authorization: Bearer …, and you're in.