# HeurChain Authentication Guide for Agents

This guide explains how automated agents and developers authenticate with HeurChain services via Model Context Protocol (MCP) and REST.

---

## 1. Overview

HeurChain supports two authentication mechanisms:

1. **OAuth 2.1 (Bearer tokens)**: Recommended for MCP clients supporting OAuth Protected Resource Metadata.
2. **Workspace API Key and Tenant Header**: Used for direct REST calls and MCP clients with custom HTTP header support.

---

## 2. OAuth 2.1 Authentication (MCP over Streamable HTTP)

The hosted MCP server is located at `https://api.heurchain.com/mcp/sse`. Choose **Streamable HTTP** (or **HTTP** in your client). The `/sse` suffix remains for compatibility. See the [official MCP Registry listing](https://registry.modelcontextprotocol.io/v0.1/servers/com.heurchain%2Fheurchain/versions/0.6.1).

### Discovery and Protected Resource Metadata

When connecting without credentials, the server returns an HTTP 401 challenge:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.heurchain.com/.well-known/oauth-protected-resource/mcp/sse", scope="openid"
```

The resource metadata document at `https://api.heurchain.com/.well-known/oauth-protected-resource/mcp/sse` specifies:

```json
{
  "authorization_servers": ["https://sprisydphgizoryvfzgt.supabase.co/auth/v1"],
  "bearer_methods_supported": ["header"],
  "resource": "https://api.heurchain.com/mcp/sse",
  "resource_name": "HeurChain memory",
  "scopes_supported": ["openid", "email", "profile"]
}
```

### Authorization Flow

1. **Discover Authorization Server**: Obtain authorization endpoints from `https://sprisydphgizoryvfzgt.supabase.co/auth/v1/.well-known/openid-configuration`.
2. **Authorize**: Prompt the user to grant access via the authorization consent interface (`/oauth/consent`).
3. **Bearer Token**: Transmit the resulting token in the `Authorization` header on all MCP requests:
   ```http
   Authorization: Bearer <access_token>
   ```

---

## 3. Workspace API Key Authentication (REST & Custom Headers)

For direct REST calls and compatible MCP clients that support custom headers, authenticate using header-based credentials.

### Required Headers

Every authenticated request requires two headers:

- `X-HeurChain-API-Key`: Your workspace API key.
- `X-HeurChain-Tenant`: Your tenant identifier.

### Obtaining Credentials

Credentials are generated in the HeurChain Dashboard at `https://heurchain.com/dashboard`. Note that a generated API key is only displayed once upon activation or key rotation.

### Example REST Request

```bash
curl -X POST https://api.heurchain.com/search \
  -H "Content-Type: application/json" \
  -H "X-HeurChain-API-Key: $HEURCHAIN_API_KEY" \
  -H "X-HeurChain-Tenant: $HEURCHAIN_TENANT_ID" \
  -d '{
    "text": "database migration conventions",
    "limit": 5
  }'
```

### Example MCP configuration (Claude Code, API-key authentication)

```json
{
  "mcpServers": {
    "heurchain": {
      "type": "http",
      "url": "https://api.heurchain.com/mcp/sse",
      "headers": {
        "X-HeurChain-API-Key": "YOUR_API_KEY",
        "X-HeurChain-Tenant": "YOUR_TENANT_ID"
      }
    }
  }
}
```

---

## 4. Security Practices

- **Never store secret keys or tokens in memory**: Do not pass passwords, API keys, private keys, or raw authentication tokens into `heurchain_store`.
- **Environment variables**: Load credentials from secure environment variables or a vault rather than hardcoding.
- **Tenant isolation**: API keys and tokens are scoped to a single workspace/tenant. Memory is shared across agents within the same authenticated tenant.
