> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn about authentication methods for GDELT Cloud

## 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

<Steps>
  <Step title="Login">
    Navigate to [gdeltcloud.com/auth/sign-in](https://gdeltcloud.com/auth/sign-in) and enter your credentials.
  </Step>

  <Step title="Session created">
    Upon successful login, a secure session cookie is created and stored in your browser.
  </Step>

  <Step title="Automatic authentication">
    All dashboard features and internal API calls are automatically authenticated using this session.
  </Step>
</Steps>

<Info>
  Sessions use secure browser cookies and include automatic token refresh for seamless long-term use.
</Info>

### 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. Use `/api/v2/*` for new integrations; `/api/v1/*` remains supported for existing direct API users.

V2 Event, Story, and Entity list calls default to the exact past 24 hours. Narrow with developer-facing filters such as `category`, `subcategory`, `country`, `region`, `continent`, date windows up to 30 days, `sort`, and pagination.

### Key Format

```
gdelt_sk_<64-hex-characters>
```

Example: `gdelt_sk_a1b2c3d4e5f6...` (64 hex chars after the prefix)

### Usage

Include the key as a Bearer token in every request:

```http theme={null}
Authorization: Bearer gdelt_sk_your_api_key_here
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://gdeltcloud.com/api/v2/events?country=India&category=Protests&subcategory=Peaceful%20protest&limit=5" \
    -H "Authorization: Bearer gdelt_sk_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests, os

  headers = {"Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"}
  resp = requests.get("https://gdeltcloud.com/api/v2/events",
                      headers=headers, params={"country": "India", "category": "Protests", "subcategory": "Peaceful protest", "limit": 5})
  ```
</CodeGroup>

## Query Units

Direct API and direct MCP calls are charged as user-controlled integrations. Hosted GDELT Cloud agents are charged as backend orchestrations:

| Surface                                      |   Usage source | QU per MCP data tool call |
| -------------------------------------------- | -------------: | ------------------------: |
| Direct REST API / direct MCP client          | `api` or `mcp` |                      1 QU |
| GDELT Cloud Agent UI                         |        `agent` |                      5 QU |
| GDELT Cloud Brief agent and scheduled Briefs |        `brief` |       0 QU; metered in BU |

### 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` | API access is not enabled for the key |
| 429  | `RATE_LIMITED`      | Request rate limit exceeded           |
| 429  | `QUOTA_EXCEEDED`    | Usage limit reached                   |

<Info>
  Generate and manage API keys in **Dashboard → Settings → API Keys**. See [API Keys](/developers/api-keys) for full details.
</Info>