Authentication

API Key Authentication

All data endpoints are authenticated via the X-API-Key HTTP header.

curl -H "X-API-Key: sk_gapi_YOUR_KEY" \
  "https://api.groundapi.net/v1/finance/stock?symbol=600519"

Getting an API Key

1. Log in to the GroundAPI Dashboard
2. Click "Create New Key"
3. Enter a key name (e.g. "Production")
4. Copy and save the key — it's only shown once at creation

Key Format

API Keys follow the format sk_gapi_ + 32 random characters, e.g.:

sk_gapi_a3b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2

The server stores only the SHA256 hash — even if the database is compromised, the original key cannot be recovered.

Rate Limiting

We use a Redis sliding window algorithm, rate-limited per user:

When the limit is exceeded, a 429 Too Many Requests is returned:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded, please try again later",
    "docs": "https://docs.groundapi.net/errors#rate_limit_exceeded"
  }
}

The response includes a Retry-After header (in seconds).

Error Codes