# Klion Agent Authentication (auth.md)

> Authentication and identity specification for AI agents accessing Klion APIs and services.
> Follows the WorkOS Agent Auth (`auth.md`) specification.

## Overview

Klion provides real-time access to the Spanish National Securities Market Commission (CNMV) official regulatory disclosures, inside information (*información privilegiada*), and issuer profiles.

AI agents can interact with Klion using three distinct authentication modes depending on security and capability requirements:
1. **Anonymous Access**: Direct read-only access for exploratory tasks and public market monitoring.
2. **Service Auth (API Key)**: Pre-provisioned API keys for continuous integration, autonomous monitoring bots, and pro workloads.
3. **Identity Assertion (ID-JAG / JWT)**: Cryptographic identity tokens minted by agent platforms or identity providers.

---

## Discovery Endpoints

- **OAuth 2.0 Protected Resource Metadata (RFC 9728)**:  
  `https://getklion.com/.well-known/oauth-protected-resource`
- **OAuth 2.0 Authorization Server Metadata (RFC 8414)**:  
  `https://getklion.com/.well-known/oauth-authorization-server`
- **Agent Skill & Discovery Index**:  
  `https://getklion.com/.well-known/ard.json`
- **LLM Context & Documentation**:  
  `https://getklion.com/llms.txt`

---

## Authentication Modes

### 1. Anonymous Access (`anonymous`)

For public search and discovery, agents may query endpoints without credentials.

- **Available Endpoints**:
  - `GET /api/v1/reports` (Search and list latest 10-50 filings)
  - `GET /api/v1/issuers` (Search listed entities and CNMV registered companies)
  - `GET /api/v1/analytics` (Summary market statistics)
- **Rate Limit**: 60 requests per minute per IP.
- **Headers**:
  ```http
  User-Agent: YourAgentName/1.0
  Accept: application/json
  ```

### 2. Service Auth (`service_auth`)

Agents with an active Klion Pro or Enterprise subscription use an API key passed in the request headers.

- **Header Format**:
  ```http
  Authorization: Bearer klion_live_your_api_key
  ```
  or
  ```http
  X-API-Key: klion_live_your_api_key
  ```
- **Capabilities**: Unrestricted queries, real-time SSE streams, full document text extraction, and webhook subscriptions.

### 3. Identity Assertion (`identity_assertion`)

Agents supporting autonomous delegation can exchange identity tokens via RFC 8693 token exchange or ID-JAG assertions.

- **Token Endpoint**: `https://getklion.com/api/auth/token`
- **Grant Type**: `urn:ietf:params:oauth:grant-type:token-exchange`
- **Supported Assertion Types**:
  - `urn:ietf:params:oauth:token-type:id-jag`
  - `urn:ietf:params:oauth:token-type:jwt`
- **Token Request Example**:
  ```http
  POST /api/auth/token HTTP/1.1
  Host: getklion.com
  Content-Type: application/x-www-form-urlencoded

  grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
  &subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid-jag
  &subject_token=<AGENT_SIGNED_ASSERTION>
  &scope=read%3Areports%20read%3Aissuers
  ```

---

## Scopes & Permissions

| Scope | Description |
|---|---|
| `read:reports` | Query and stream CNMV regulatory announcements, inside information, and AI executive summaries. |
| `read:issuers` | Search corporate directory, tickers, CIF numbers, and issuer metadata. |
| `read:analytics` | Access aggregated market filing distribution and historical volume analytics. |

---

## Quickstart for Agents

### cURL

```bash
# Public query
curl -s "https://getklion.com/api/v1/reports?search=Santander&type=IP"

# Authenticated query
curl -s "https://getklion.com/api/v1/reports?search=Telef%C3%B3nica" \
  -H "Authorization: Bearer $KLION_API_KEY"
```

### Python

```python
import os
import requests

api_key = os.getenv("KLION_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}

response = requests.get(
    "https://getklion.com/api/v1/reports",
    params={"search": "dividendo", "type": "OIR", "limit": 5},
    headers=headers,
    timeout=10,
)
data = response.json()
print(data)
```

---

## Support & Verification

- **Developer Portal**: https://getklion.com/developers
- **Technical Contact**: info@getklion.com
- **Wikidata Entity**: https://www.wikidata.org/wiki/Q141345675