Authentication

By the end of this guide, you'll know how Plaza auth works and never get a mystery 401 again.

The short version

Every request needs an x-api-key header. No key, no response.

curl "https://plaza.fyi/api/v1/elements?type=node&id=1" \

  -H "x-api-key: pk_live_YOUR_KEY"

Getting a key

  1. Sign in at plaza.fyi/auth/login
  2. Go to Dashboard > API Keys
  3. Click "Create Key", give it a name

The full key is shown exactly once. Copy it immediately. Plaza stores a salted hash, so if you lose it, you'll need to create a new one. The pk_live_ prefix is always visible in your dashboard so you can tell keys apart.

Rate limits

Limits are per plan, enforced per minute with a burst allowance per second:

Plan Requests/min Burst
Free 60 10/sec
Starter 300 50/sec
Growth 1,000 100/sec
Enterprise 10,000 1,000/sec

Every response includes three headers you should pay attention to:

x-ratelimit-limit: 60

x-ratelimit-remaining: 58

x-ratelimit-reset: 1710340800

x-ratelimit-remaining tells you how many requests you have left in the current window. x-ratelimit-reset is a Unix timestamp -- when that time comes, your counter resets. If you hit zero, you get a 429 Too Many Requests until the reset.

The smart move is to check x-ratelimit-remaining proactively rather than waiting to get rate limited. If it's getting low, back off.

Free tier cap

Free accounts get 10,000 API calls per month. After that, requests return 402 Payment Required until the billing cycle rolls over. Upgrade from the billing page to remove the cap.

Revoking and rotating keys

Go to Dashboard > API Keys and click "Revoke" next to any key. It takes effect immediately -- any in-flight requests with that key will fail.

If you need zero-downtime rotation:

  1. Create a new key
  2. Update your application to use the new key
  3. Verify it works
  4. Revoke the old key

Multiple keys

Create as many keys as you need. Each one has its own independent usage tracking and rate limit counter. Name them something useful -- "production-backend", "staging", "ci-tests" -- so if one leaks, you know exactly which one to revoke without disrupting everything else.

Common auth errors

You see It means Fix
401 with missing_key No x-api-key header Add the header to your request
401 with invalid_key Key doesn't match anything Check for typos, make sure you're using the full key
401 with revoked_key Key was revoked Create a new key from the dashboard
402 with quota_exceeded Free tier monthly cap hit Upgrade your plan or wait for the next billing cycle
429 with rate_limited Too many requests too fast Check x-ratelimit-reset and wait