PortalSign In
Authentication

Authenticate requests and handle limits correctly.

Every protected endpoint under /api/v1 uses the same API key header. This page covers auth, quota signals, rate limits, and the JSON failure shapes clients should expect.

Docs OverviewSearch DocsOpenAPIFAQ
Authentication

Headers, Rate Limits, And Access Rules

Protected endpoints live under /api/v1/* and use API key auth at the route layer.

All protected endpoints require the header below on every request.

X-NFLMeta-Key: <YOUR_KEY>

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Policy, and monthly quota headers where applicable.

Prefer this order for new integrations: focused slice, then /{field} drilldown, then broader composite endpoint, then raw reference export only when you explicitly need database-shaped rows.

Missing API Key

HTTP/1.1 401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "message": "missing api key",
    "status": 401
  }
}

Valid API Key

HTTP/1.1 200 OK
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19
X-Monthly-Quota-Remaining: 4944
{
  "data": { ... }
}

Rate Limited

HTTP/1.1 429 Too Many Requests
{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded",
    "status": 429
  }
}
Richer Example

Authenticated team request with quota headers

This is the standard success path most clients should validate first before expanding into broader endpoint families.

Request

curl -i -H 'X-NFLMeta-Key: YOUR_KEY' https://nflmeta.org/api/v1/teams/NE

What To Look For

HTTP/1.1 200 OK
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19
X-Monthly-Quota-Remaining: 4944
Richer Example

Graceful client handling for auth failure

Clients should branch on structured error fields instead of trying to pattern-match messages or redirects.

Client Rule

if (!response.ok) {
  const body = await response.json();
  if (body.error?.status === 401) {
    throw new Error("API key missing or invalid");
  }
}
Errors & Limits

What Clients Should Expect

  • Inspect error.code and error.status, not just the message string.
  • Use rate-limit headers to pace retries and queue work instead of polling blindly.
  • Treat list filters and identifier discovery as the normal way to avoid avoidable 404 responses.
  • Keep protected requests on the API key path; site login is not part of normal API authentication.