Skip to main content

API Keys

All PrairieCloud API endpoints require authentication via an API key. This guide covers everything you need to know about creating, using, rotating, and securing your keys.

Getting an API Key​

Manage your API keys in the Developer Dashboard.

  1. Sign up at dashboard.prairiecloud.io
  2. Navigate to Keys in the left sidebar
  3. Click Create API Key
  4. Give your key a descriptive name (e.g., production, my-research-project)
  5. Copy the key immediately — it is shown only once

Keys are prefixed with pck_live_ and have the format:

pck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
One-time display

For security, the full key is shown only at creation time. If you lose it, you'll need to rotate (which generates a new key and revokes the old one).

Using the X-API-Key Header​

Include your API key in the X-API-Key request header:

curl -H "X-API-Key: pck_live_YOUR_KEY_HERE" \
  "https://api.prairiecloud.io/v1/data?variables=pop_total&geo=state:48"

The header name is case-insensitive per HTTP spec. All of these are equivalent:

X-API-Key: pck_live_...
x-api-key: pck_live_...
X-Api-Key: pck_live_...

Alternative: Query Parameter​

For quick testing, you can pass the key as a query parameter. Do not use this in production — query parameters appear in server logs and browser history:

curl "https://api.prairiecloud.io/v1/data?variables=...&geo=...&api_key=pck_live_..."

Key Rotation​

Rotate a key when:

  • You suspect it has been compromised
  • You want to retire a key used by a former team member
  • You're rotating as part of a regular security policy

Steps:

  1. In the dashboard, go to Keys → click your key → Rotate Key
  2. A new key is generated and the old one is revoked simultaneously
  3. Update your application to use the new key
  4. Verify your application works with the new key
Zero-downtime rotation

We recommend creating a second key, migrating your application to it, then revoking the first key. This avoids any gap in service.

Revoking a Key​

To permanently disable a key:

  1. Dashboard → Keys → click your key → Revoke Key
  2. Confirm the action

A revoked key immediately returns 401 Unauthorized on any request. Revocation cannot be undone.

Security Best Practices​

Never embed your API key in source code. Use environment variables:

# In your shell / deployment environment:
export PRAIRIECLOUD_API_KEY="pck_live_..."
# Python
import os
api_key = os.environ["PRAIRIECLOUD_API_KEY"]
// Node.js
const apiKey = process.env.PRAIRIECLOUD_API_KEY;

Never commit your key to version control. Add .env files to .gitignore. Use a secret manager (AWS Secrets Manager, GitHub Actions Secrets, etc.) in CI/CD pipelines.

Use one key per environment. Maintain separate keys for development, staging, and production. This lets you revoke a compromised key without affecting other environments.

Audit regularly. Review your active keys in the dashboard. Revoke any keys that are no longer needed.

What to Do If a Key Is Compromised​

  1. Immediately revoke the key from the dashboard
  2. Check your usage logs for unauthorized requests
  3. Create a new key and deploy it to your application
  4. If you suspect data exfiltration, contact [email protected]

Error Responses​

ResponseMeaning
401 UnauthorizedKey is missing, invalid, or revoked
429 Too Many RequestsRate limit exceeded — see Rate Limiting

See the Error Handling guide for the full error response format.

Billing & Plan Management​

View pricing and upgrade at Billing. Upgrading increases your monthly quota and per-minute burst limit.

Next Steps​