# Eriqa, Agent Authentication

Eriqa exposes call intelligence, competency, QA, insights and coaching
tools to AI agents over MCP (`https://mcp.eriqa.io`) and the
headless REST API (`https://yfevoukvzwbhfmkkiprn.supabase.co/functions/v1/headless-api`).

Agents authenticate with a **Personal Access Token (PAT)** issued by the
Eriqa platform.

- Canonical URL: https://eriqa.io/auth.md
- Discovery: linked from `/.well-known/oauth-protected-resource` (`agent_auth` block)
- Last updated: 2026-07-15

---

## 1. Register (one-time, human)

Agent registration is human-in-the-loop. Anonymous or self-service agent
registration is not currently supported, Eriqa is a private B2B
platform and every token must be attributable to a real account and user.

1. A human account owner signs in at https://eriqa.io/login
2. Open **Settings → Headless Access**: https://eriqa.io/app/settings
3. Click **New token**, name it (e.g. "Claude Code", "ChatGPT", "Cursor"),
   pick scopes and (optionally) set a monthly LLM-token cap
4. Copy the `iqa_pat_…` value shown once. Save it in a password manager or
   your agent's secret store, it is not displayed again

## 2. Present the token

Every request MUST carry the PAT via one of:

**Preferred, HTTP header:**

```
Authorization: Bearer iqa_pat_xxx
```

**Fallback, query string** (for MCP clients that cannot inject headers):

```
https://mcp.eriqa.io?token=iqa_pat_xxx
```

The token identifies both the calling agent AND the Eriqa account it
acts on behalf of. There is no client-credentials flow, no dynamic client
registration and no user impersonation.

Keys issued before the Eriqa prefix change start with `di_pat_` and remain valid.

## 3. Scopes

| Scope | Grants |
| --- | --- |
| `read`  | List and read calls, competency assessments, QA scorecards, reports, insights, playbooks, coaching plans, team and client data |
| `write` | Trigger report generation, schedule automations, upload calls, mutate coaching plans and playbook documents |

`read` alone is enough for the Q&A, spot-check and analytics surface. Only
grant `write` when the agent needs to create or mutate data.

## 4. Rate limiting and cost control

- Per-token monthly LLM-token cap (set at issuance, editable in Settings)
- 429 responses include `Retry-After` seconds
- All grounded `ask()` calls debit against the cap; unrelated read tools do not

## 5. Rotation and revocation

- Tokens can be revoked at any time from Settings → Headless Access
- There is no rotation grace period, a revoked token immediately returns 401
- On 401, prompt the user to mint a new PAT and reconnect

## 6. What agents can do

Full catalogue: https://eriqa.io/openapi.json, machine surfaces
enumerated at https://eriqa.io/.well-known/api-catalog

Human docs: https://eriqa.io/mcp

## 7. Contact

Security issues: privacy@eriqa.io
Product / integrations: hello@eriqa.io