# SoMerch auth.md

This document describes how AI agents and automated clients authenticate
against the SoMerch API. It follows the [auth.md](https://github.com/workos/auth.md)
convention for agent registration discovery.

## Audience

AI agents, autonomous workflows, and server-to-server integrations that
need to call SoMerch HTTP APIs on behalf of a user account or
anonymously against public endpoints.

## Discovery

| Document | URL |
| --- | --- |
| API catalog (RFC 9727) | https://somerch.co/.well-known/api-catalog |
| Protected resource metadata (RFC 9728) | https://somerch.co/.well-known/oauth-protected-resource |
| Authorization server metadata (RFC 8414) | https://somerch.co/.well-known/oauth-authorization-server |
| OpenID Connect discovery | https://somerch.co/.well-known/openid-configuration |
| OpenAPI 3.1 specification | https://somerch.co/api/public/openapi.json |
| Human documentation | https://somerch.co/api-docs |

## Registration

Programmatic agent registration is **human-mediated**. A human operator
creates a SoMerch account, then shares the resulting credentials with
the agent.

- **Registration URI:** https://somerch.co/auth
- **Signup endpoint (Supabase):** `POST https://icgeebswaukzsuazxqcj.supabase.co/auth/v1/signup`
- **Token endpoint (Supabase):** `POST https://icgeebswaukzsuazxqcj.supabase.co/auth/v1/token?grant_type=password`
- **Revocation endpoint (Supabase):** `POST https://icgeebswaukzsuazxqcj.supabase.co/auth/v1/logout`

Dynamic Client Registration (RFC 7591) is not currently supported.

## Supported identity types

### Anonymous

Public read-only endpoints under `/api/public/*` accept unauthenticated
calls and require no agent registration. When the Supabase project has
anonymous sign-in enabled, an agent can mint a short-lived anonymous
bearer JWT:

- **Claim URI:** `https://icgeebswaukzsuazxqcj.supabase.co/auth/v1/signup`
- **Credential type:** `bearer_jwt`
- **Use:** `Authorization: Bearer <jwt>` against `/api/protected/*`.

### Identity assertion (verified email + password)

For human-provisioned accounts:

- **Claim URI:** `https://icgeebswaukzsuazxqcj.supabase.co/auth/v1/token?grant_type=password`
- **Assertion type:** `verified_email`
- **Credential type:** `bearer_jwt`
- **Use:** `Authorization: Bearer <jwt>` against `/api/protected/*`.

## Token use

Present the bearer token on every protected request:

```
GET https://somerch.co/api/protected/me
Authorization: Bearer <jwt>
```

On 401 responses, protected endpoints return a `WWW-Authenticate`
header with a `resource_metadata` parameter (RFC 9728), so agents can
auto-discover the full authentication chain.

## Revocation

Call `POST https://icgeebswaukzsuazxqcj.supabase.co/auth/v1/logout` with the bearer token to invalidate the
current session.

## Contact

- API docs: https://somerch.co/api-docs
- Support: support@somerch.co