Security & Auth

API Key Authentication

The WSO Options Data API authenticates requests using secret API keys transmitted via HTTP Bearer token headers.

Keys are secret, so call the API from your server or scripts, never from a web page. The API does not support CORS: browser requests from other sites are refused. To use the data in a web app, call the API from your own backend.

Authorization Header Format

Every protected endpoint requires an HTTP Authorization header. Keys start with the prefix wso_live_ followed by 49 letters and digits (the last six are a checksum, so a mistyped key is rejected without a lookup).

http

Authorization: Bearer wso_live_YOURKEYHERExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Verifying API Key Status

You can test your API key and check its plan with the lightweight verification endpoint GET /v1/auth/verify. Like every call, it counts as one request against your per-minute rate limit.

bash

curl "https://api.wheelstrategyoptions.com/v1/auth/verify" \
  -H "Authorization: Bearer $WSO_API_KEY"

Successful 200 OK response:

json

{
  "key_id": 2,
  "key_prefix": "wso_live_YOURKEY",
  "status": "authenticated",
  "plan": "basic",
  "subscription_status": "active",
  "entitled": true,
  "entitlement_reason": ""
}

Key Quotas & Security Hygiene

Maximum 5 Active Keys

Each user account is permitted a maximum of 5 active API keys at a time. Revoke unused or compromised keys from the dashboard before issuing new ones.

Environment Variables Only

Never commit secret keys into client-side web applications, public Git repositories, or mobile bundles. Store keys in secure environment variables.

Common Authentication Errors

Status	Error Code	Cause & Resolution
401	missing_auth	Missing `Authorization` header. Add `Authorization: Bearer <key>` to your request.
401	invalid_auth	Missing `Bearer` prefix before the token. Make sure a space separates Bearer and your token.
403	wrong_credential_type	A Firebase ID token or dashboard session credential was sent to /v1; use an API key (`wso_live_...`) instead. Legacy `wsk_...` keys return `invalid_key` (401).
401	invalid_key	Key does not exist, has expired, or has been explicitly revoked or deleted in the dashboard (including legacy `wsk_...` keys).
403	plan_upgrade_required	The API key is valid, but the target endpoint requires an active subscription plan (e.g. Basic plan required).
403	trial_ended	The in-app trial has ended. Subscribe to an active plan in the developer dashboard to keep querying data endpoints.

Legacy wsk_ Keys Discontinued

Previous generation wsk_ keys are discontinued and rejected by the API authentication gateway. Always use wso_live_ keys generated from the modern dashboard.

← Quickstart Rate Limits →