# Tanso — Agent Authentication Guide

How AI agents and automated systems authenticate with Tanso APIs.

---

## Platform API (dashboard.tansohq.com)

The Tanso Client API uses API keys for authentication. Every request must include a key.

### Step 1: Get your API key

1. Sign up at [dashboard.tansohq.com](https://dashboard.tansohq.com)
2. Go to **Settings > API Keys**
3. Click **Generate API Key**
4. Copy the key — it starts with `sk_test_` (sandbox) or `sk_live_` (production)

### Step 2: Authenticate requests

Pass your key in one of two ways:

```
Authorization: Bearer sk_test_your_api_key
```

or

```
X-API-Key: sk_test_your_api_key
```

### Step 3: Verify

```bash
curl -H "Authorization: Bearer sk_test_your_api_key" \
  https://api.tansohq.com/api/v1/client/plans
```

A successful response returns `{"success": true, "data": [...]}`.

### Environments

| Environment | Base URL | Key prefix |
|-------------|----------|------------|
| Production | `https://api.tansohq.com` | `sk_live_` |
| Sandbox | `https://sandbox.api.tansohq.com` | `sk_test_` |

### Permissions

API keys grant full access to the Client API (`/api/v1/client/**`). All keys are scoped to your account — you can only access your own customers, subscriptions, and billing data. Tenant isolation is enforced at the database level.

### Key management

- Keys can be rotated from the dashboard at any time
- Keys support expiration dates
- Revoke a key instantly by deleting it in the dashboard
- Both old and new keys work during rotation until the old one is deleted

### Error responses

| Status | Meaning |
|--------|---------|
| `401` | Invalid or missing API key |
| `403` | Key is valid but access is denied |
| `409` | Duplicate event (idempotency key already used) |

### Idempotency

For event ingestion and write operations, include an idempotency key to make retries safe:

```bash
curl -X POST https://api.tansohq.com/api/v1/client/events \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: evt_unique_123" \
  -d '{"eventName": "api_call", "occurredAt": "2026-01-15T14:30:00Z", "customerReferenceId": "cust_123", "usageUnits": 1}'
```

---

## MCP Server (Model Context Protocol)

Tanso exposes an MCP server for AI agent integration. Same API key, different protocol.

### Connection

| Environment | Endpoint |
|-------------|----------|
| Production | `https://api.tansohq.com/mcp` |
| Sandbox | `https://sandbox.api.tansohq.com/mcp` |

### Configuration

Add to your MCP client config (Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "tanso": {
      "url": "https://api.tansohq.com/mcp",
      "headers": {
        "X-API-Key": "sk_live_your_api_key_here"
      }
    }
  }
}
```

No additional handshake or session management required. Each tool call is independently authenticated.

34 tools available across billing, entitlements, events, plans, customers, credits, and Stripe integration. See [llms-mcp.txt](https://www.tansohq.com/llms-mcp.txt) for the full tool reference.

---

## Observe (observe.tansohq.com)

Observe uses SDK API keys for event ingestion and Clerk for dashboard access.

### SDK Key (for event ingestion)

1. Sign up at [observe.tansohq.com](https://observe.tansohq.com)
2. Go to **Settings > SDK Keys**
3. Generate a key
4. Pass it as a Bearer token:

```bash
curl -X POST https://observe.tansohq.com/api/events/ingest \
  -H "Authorization: Bearer your_sdk_key" \
  -H "Content-Type: application/json" \
  -d '{"events": [...]}'
```

### Gateway proxy (OpenAI/Anthropic)

Observe can proxy your AI provider calls to automatically capture cost data:

```bash
# Instead of calling OpenAI directly:
curl https://observe.tansohq.com/api/v1/chat/completions \
  -H "Authorization: Bearer your_openai_key" \
  -H "X-Observe-Key: your_sdk_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [...]}'
```

### Rate limits

| Endpoint | Limit |
|----------|-------|
| Auth | 20 requests / 15 min |
| API | 60 requests / min |
| Insights | 5 requests / min |

---

## Data Lab (data.tansohq.com)

Data Lab's MCP server is public for read operations — no authentication required.

### MCP Connection

```json
{
  "mcpServers": {
    "tanso-data-lab": {
      "url": "https://data.tansohq.com/api/mcp"
    }
  }
}
```

6 query tools available: `query_companies`, `read_page`, `search_wiki`, `list_field_values`, `dataset_stats`, `list_changes`.

---

## OpenAPI Specification

The full API specification is available at:

- JSON: [https://www.tansohq.com/openapi.json](https://www.tansohq.com/openapi.json)
- Interactive docs: Available at runtime via Swagger UI on the API server

---

## Resources

- [llms.txt](https://www.tansohq.com/llms.txt) — Product overview and API summary
- [llms-mcp.txt](https://www.tansohq.com/llms-mcp.txt) — MCP server tool reference (34 tools)
- [openapi.json](https://www.tansohq.com/openapi.json) — OpenAPI 3.1 specification
- [Java SDK](https://github.com/tansoflow/tanso-java-sdk) — Official Java client