Overview
GDELT Cloud supports multiple authentication methods depending on your use case:| Method | Use Case | Where |
|---|---|---|
| Session Auth | Web dashboard, interactive use | Browser |
| API Keys | Programmatic access, automation | REST API, MCP Server |
Session Authentication
Session authentication is used when accessing GDELT Cloud through the web dashboard.How It Works
Login
Navigate to gdeltcloud.com/auth/sign-in and enter your credentials.
Session created
Upon successful login, a secure session cookie is created and stored in your browser.
Sessions are powered by Supabase Auth and include automatic token refresh for seamless long-term use.
Session Security
- Sessions expire after 7 days of inactivity
- HTTPS-only cookies prevent interception
- CSRF protection on all state-changing operations
- Optional two-factor authentication (coming soon)
API Key Authentication
API keys provide programmatic access to the Developer API (/api/v1/*). Required for all v1 endpoints.
Key Format
gdelt_sk_a1b2c3d4e5f6... (64 hex chars after the prefix)
Usage
Include the key as a Bearer token in every request:Plan Requirements
| Plan | API Access | Monthly QU | RPM |
|---|---|---|---|
| Free / Scout | ✗ | — | — |
| Analyst | ✓ | 10,000 | 30 |
| Professional | ✓ | Unlimited | 120 |
Authentication Errors
| HTTP | Code | Meaning |
|---|---|---|
| 401 | MISSING_API_KEY | No Authorization header |
| 401 | INVALID_API_KEY | Wrong format or revoked key |
| 403 | API_ACCESS_DENIED | Plan does not include API access |
| 429 | RATE_LIMITED | Per-minute RPM exceeded |
| 429 | QUOTA_EXCEEDED | Monthly QU limit reached |
Generate and manage API keys in Dashboard → Settings → API Keys. See API Keys for full details.