# auth.md — Attrove Agent Authentication & Registration

Attrove is communication intelligence for AI products: query a user's email,
Slack, calendar, meetings, and notes — and watch outcomes (Goals) that catch the
conversations going quiet — through one authenticated retrieval surface.

This document tells an AI agent or developer how to register, obtain
credentials, and authenticate. Machine-readable discovery documents are linked
at the end.

## Two ways to connect

**1. Hosted MCP (end-user agents) — recommended**

- Endpoint: `https://api.attrove.com/mcp` (Streamable HTTP)
- Auth: OAuth 2.1. MCP clients (Claude, ChatGPT, Cursor, Codex) run the OAuth
  flow automatically; the end user authorizes access to their own account.
- Install helpers: `npx @attrove/cli install <claude-code|cursor|claude-desktop|codex>`
- OAuth resource metadata: `https://attrove.com/.well-known/oauth-protected-resource`

**2. Partner / server-to-server API**

- For products that provision and query on behalf of their own users.
- Base URL: `https://api.attrove.com`
- Register: sign up free at `https://connect.attrove.com/auth/signup` (no credit
  card) to create an organization and issue credentials.

## Registration

- **End-user agents** register via OAuth 2.1 Dynamic Client Registration
  (RFC 7591). MCP clients do this automatically; the `registration_endpoint` is
  advertised in `https://attrove.com/.well-known/oauth-authorization-server`
  (also surfaced as `agent_auth.register_uri`). End users then authorize access
  to their own account.
- **Partners / services** register by signing up at
  `https://connect.attrove.com/auth/signup` to obtain `client_id` +
  `client_secret`, then provision their own users.

## Credential types

| Credential | Form | Use |
| --- | --- | --- |
| Client credentials | `client_id` + `client_secret` | Server-side. Provision users, rotate tokens, create connect sessions. |
| User API key | `sk_…` bearer | Permanent per-user key, sent as `Authorization: Bearer sk_…`. On the REST API the user is the `:user_id` path segment (`/v1/users/:user_id/…`); on hosted MCP / A2A, pass `X-Attrove-User-Id: <user_id>`. |
| End-user OAuth | OAuth 2.1 bearer (JWT) | End user authenticates as themselves (hosted MCP / A2A). |

`pit_` integration tokens are short-lived, single-use, and minted internally
during connect-session activation — agents do not handle them directly.

## Server-to-server flow

1. Obtain `client_id` + `client_secret` (sign up at `connect.attrove.com`).
2. Provision a user → receive that user's `sk_` key.
3. When live OAuth is needed, create a durable connect session and hand the user
   its `activation_url` to authorize Gmail / Slack / Calendar — or push scoped
   context via the push API.
4. Query the user's data with the `sk_` key.

Full reference: `https://attrove.com/llms-full.txt` and the OpenAPI spec at
`https://api.attrove.com/openapi.json`.

## Token lifecycle & revocation

- Rotate `client_secret` and revoke or rotate `sk_` keys from the dashboard at
  `https://connect.attrove.com`.
- `pit_` tokens expire automatically (single-use, ~10 minutes).
- Access is scoped per user; identify the user via the `:user_id` path segment
  (REST API) or the `X-Attrove-User-Id` header (hosted MCP / A2A).

## Discovery documents

- OAuth Protected Resource (RFC 9728): `https://attrove.com/.well-known/oauth-protected-resource`
- OAuth Authorization Server (RFC 8414): `https://attrove.com/.well-known/oauth-authorization-server`
- A2A Agent Card: `https://attrove.com/.well-known/agent-card.json`
- MCP Server Card: `https://attrove.com/.well-known/mcp/server-card.json`
- API catalog: `https://attrove.com/.well-known/api-catalog`
- OpenAPI 3.1: `https://api.attrove.com/openapi.json`
- A2A interface: `https://api.attrove.com/a2a/v1`

Questions: `https://attrove.com`.