Authentication

The API supports three authentication methods depending on your use case.

API Key (recommended for programmatic access)

API keys are the simplest way to authenticate for data consumption. Available to Sharp-tier subscribers.

curl -H "X-API-Key: $NBAV3_DATA_TOKEN" \
  https://nbaproplab.com/api/v1/data/picks/today

Creating an API key

# Requires a JWT Bearer token (see below)
curl -X POST https://nbaproplab.com/api/v1/me/api-keys \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-notebook"}'

The response includes rawKey — save it immediately, it’s only shown once.

Key management

Action	Endpoint
List keys	`GET /api/v1/me/api-keys`
Create key	`POST /api/v1/me/api-keys`
Revoke key	`DELETE /api/v1/me/api-keys/{id}`

JWT Bearer token (for user sessions)

Used by the web dashboard and for creating API keys. Short-lived (15 minutes) with a rotating refresh token.

# 1. Login to get tokens
curl -X POST https://nbaproplab.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

# Response includes accessToken (15 min) + HttpOnly refresh cookie (30 days)

# 2. Use the access token
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://nbaproplab.com/api/v1/data/picks/today

# 3. Refresh when expired (automatic in SDKs)
curl -X POST https://nbaproplab.com/api/v1/auth/refresh \
  --cookie "refreshToken=..."

Ops token (for admin automation)

Operations tokens authenticate against the /api/v1/ops endpoints for infrastructure monitoring and pipeline control.

curl -H "Authorization: Bearer $NBAV3_OPS_TOKEN" \
  https://nbaproplab.com/api/v1/ops/health

Ops tokens are created by admins:

curl -X POST https://nbaproplab.com/api/v1/ops/tokens \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "monitoring", "scopes": ["ops:read"]}'

Ops scopes

Scope	Access
`ops:read`	Health, services, jobs, pipeline runs, errors, freshness
`ops:commands`	Queue and cancel operations (score-day, settle, ingest)
`ops:config`	Read and write app configuration
`ops:tokens`	Manage ops tokens

Access tiers

Not all endpoints are available to all users:

Tier	Data API	Ops API	Limits
Free	No access	No access	—
Pro	No access	No access	—
Sharp	Full access	No access	Rate-limited
Admin	Full access	Full access	No limits

Error responses

Authentication failures return RFC 9457 problem details:

{
  "type": "https://nbaproplab.com/errors/unauthorized",
  "title": "Authentication required",
  "status": 401,
  "detail": "No valid authentication token provided"
}

Status	Meaning
`401`	Missing or invalid token/key
`403`	Valid auth but insufficient tier or scope
`429`	Rate limit exceeded