Authentication

Authenticate every request with an API key via the HTTP header:

X-API-Key: <dev_demo_123>

Key format

• Development keys start with pp_dev_…
• Production keys start with pp_live_…
• Keys are long‑lived secrets. Treat them like passwords.

Tip: Track the response header x-request-id in your logs/support tickets so we can quickly trace any issue.

---

Quick check

Use your key against the public health endpoint:

cURL

curl -s \
  -H "X-API-Key: $PORTPULSE_API_KEY" \
  https://api.useportpulse.com/v1/health

Python

import os, requests
API_KEY = os.getenv("PORTPULSE_API_KEY", "dev_demo_123")
r = requests.get(
    "https://api.useportpulse.com/v1/health",
    headers={"X-API-Key": API_KEY}, timeout=15
)
print(r.status_code, r.json())
print("x-request-id:", r.headers.get("x-request-id"))

JavaScript (fetch)

const API_KEY = process.env.PORTPULSE_API_KEY || "dev_demo_123";
const res = await fetch("https://api.useportpulse.com/v1/health", {
  headers: { "X-API-Key": API_KEY },
});
console.log(res.status, await res.json());
console.log("x-request-id:", res.headers.get("x-request-id"));

---

Using environment variables

Store your key in an environment variable instead of hardcoding it.

# macOS/Linux (temporary for the current shell)
export PORTPULSE_API_KEY="pp_live_xxxxxxxxxxxxx"

# or use a .env file with a loader (dotenv, python-dotenv, etc.)

In CI or serverless platforms, set PORTPULSE_API_KEY in the project’s secret settings.

---

Common errors

Status	Meaning	Typical cause	How to fix
401	Unauthorized	Missing header or malformed key	Send X-API-Key and verify the value/prefix
403	Forbidden	Key disabled or plan lacks access	Rotate/enable key; upgrade plan if endpoint is restricted
429	Too Many Requests	You were rate‑limited	See Rate limits; respect Retry-After
5xx	Server error	Transient issue	Retry with jitter/backoff; share x-request-id with support

Related docs: Rate limits · Errors

---

Response headers you may see

Header	Description
x-request-id	Unique id for this request – include in support tickets
RateLimit-Limit	Your current request-per-minute allotment
RateLimit-Remaining	Remaining requests in the current window
RateLimit-Reset	UTC epoch seconds when the window resets
Retry-After	Seconds to wait before retrying (sent on 429)
ETag	Strong validator for CSV endpoints – see CSV & ETag

---

Security best practices

• Do not embed keys in frontend/mobile apps.
• Keep separate keys for dev (pp_dev_*) and prod (pp_live_*).
• Rotate immediately if leaked; contact us to revoke a compromised key.
• Restrict who can access the key in CI, servers, and notebooks.

---

Postman / Insomnia

Use a workspace variable called PORTPULSE_API_KEY and set the default Auth header:

Key: X-API-Key
Value: {{PORTPULSE_API_KEY}}

See guides: Postman · Insomnia

---

Next steps

• Try a real dataset:

  curl -H "X-API-Key: $PORTPULSE_API_KEY" \
    "https://api.useportpulse.com/v1/ports/USLAX/trend?days=30&format=json"

• Explore the full API in the OpenAPI page from the navbar.

If you hit any issue, send us the x-request-id and timestamp – we’ll trace it for you.