# Tanso — Agent Authentication Guide

How AI agents and automated systems authenticate with a Tanso instance.

Tanso is self-hosted. There is no hosted API at tansohq.com — every request
goes to an instance you (or the operator you work with) run. Replace
`YOUR-INSTANCE` below with that deployment's host.

---

## Client API

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

### Step 1: Get an API key

1. Open your instance's admin dashboard
2. Go to **Settings > API Keys**
3. Click **Generate API Key**
4. Copy the key. It starts with `sk_test_` or `sk_live_`

If you don't have an instance yet, the quickstart takes a few minutes:
https://tanso.mintlify.app/quickstart

### 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://YOUR-INSTANCE/api/v1/client/plans
```

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

### Permissions

API keys grant full access to the Client API (`/api/v1/client/**`). All keys
are scoped to the account they were created in. 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://YOUR-INSTANCE/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)

Every Tanso instance can expose an MCP server at `/mcp`. It is off by default;
the operator enables it in config. Same API key, same account scoping as the
REST API — there is no separate, weaker path for agents.

### Configuration

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

```json
{
  "mcpServers": {
    "tanso": {
      "url": "https://YOUR-INSTANCE/mcp",
      "headers": {
        "X-API-Key": "sk_live_your_api_key_here"
      }
    }
  }
}
```

No additional handshake or session management required. Each tool call is
independently authenticated. Tools that spend money or make hard-to-reverse
changes require an explicit `confirmAction: true` argument.

Setup and the full tool catalog: https://tanso.mintlify.app/mcp

---

## Resources

- [llms.txt](https://tansohq.com/llms.txt) — product overview
- [AGENTS.md](https://tansohq.com/AGENTS.md) — agent integration guide
- [Documentation](https://tanso.mintlify.app) — full docs
- [Source](https://github.com/tansohq/tanso-oss) — AGPL-3.0
- [TypeScript SDK](https://www.npmjs.com/package/@tansohq/sdk)