# How agents authenticate with Aihoo! (auth.md)

This document tells an autonomous agent everything it needs to obtain
authorized access to the Aihoo! APIs without human guesswork.

## 1. Choose an identity type

| Identity type | When to use | How to obtain credentials |
| --- | --- | --- |
| `anonymous` | Reading public discovery documents only (llms.txt, .well-known/*, markdown companions) | No credentials needed — just fetch |
| `identity_assertion` | Calling MCP tools or audit APIs on behalf of a user | OAuth 2.0 authorization code flow (below) |

Public, read-only discovery endpoints never require authentication. Any
endpoint that reads or writes user data requires an OAuth 2.0 access token.

## 2. OAuth 2.0 flow (identity_assertion)

Authorization server metadata (RFC 8414):
`https://aihoo.app/.well-known/oauth-authorization-server.json`

Protected resource metadata (RFC 9728):
`https://aihoo.app/.well-known/oauth-protected-resource.json`

1. **Register / sign in** at `https://aihoo.app/auth` (free self-serve plan,
   no credit card). This is the `register_uri` for agent onboarding.
2. Send the user to the authorization endpoint:
   `https://egkekjdzyiytrwjvhadi.supabase.co/auth/v1/authorize`
   with `response_type=code` and PKCE (`code_challenge_method=S256`).
3. Exchange the code at the token endpoint:
   `https://egkekjdzyiytrwjvhadi.supabase.co/auth/v1/token`
4. Call APIs with `Authorization: Bearer <access_token>`.

### Scopes

- `openid` — OpenID Connect identity
- `profile` — basic profile (name)
- `email` — email address
- `mcp:read` — read access to MCP tools (companies, audits, comparisons,
  tracked domains)

### Assertion types

`identity_assertion` supports `verified_email` and
`urn:ietf:params:oauth:token-type:id_token` assertions, issued as OAuth 2.0
access tokens (`credential_types_supported: oauth2_access_token`).

## 3. Handle errors and throttling

- All 4xx/5xx responses are typed JSON (RFC 9457): a machine-readable `error`
  code plus a human-readable `message`.
- `401 unauthenticated` → re-run the OAuth flow (token expired).
- `403 not_authorized` → the user lacks plan/quota for this feature.
- `429 rate_limited` → respect `Retry-After` and the `RateLimit-*` headers
  (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`).

## 4. Versioning and deprecation

The API is versioned in the OpenAPI document (`info.version`). Breaking
changes are announced at `https://aihoo.app/developers` at least 90 days in
advance and signalled in responses with `Deprecation` and `Sunset` (RFC 8594)
headers. Never integrate against undocumented endpoints.