# auth.md

PeptidesDirect (peptidesdirect.io) is an EU research-peptide shop. This document
describes how an AI agent acting on behalf of a signed-in PeptidesDirect customer
can read that customer's own order history, using OAuth 2.1 with PKCE and the
Model Context Protocol (MCP).

## Who this is for

AI agents (personal assistants, shopping agents) acting on behalf of a customer who
already has a PeptidesDirect account and wants their agent to check on orders they
placed. This is **read-only** and requires the customer's explicit, interactive
consent: every authorization asks the signed-in customer to approve or deny the
request on peptidesdirect.io. There is no way to place, change or cancel an order
through this flow.

## What agents get

A single scope, `orders:read`, against one MCP endpoint:
<https://peptidesdirect.io/mcp/account> (POST, Streamable HTTP, stateless,
requires `Authorization: Bearer <access token>`). Tools exposed there:

- `list_my_orders`: the customer's own orders (order number, status, date, total)
- `get_my_order`: full detail for one order (items, totals, payment, shipment
  tracking)
- `get_my_profile`: the customer's own name, email, member-since date

## How to register

Public client, dynamic registration (RFC 7591), no approval step, no client secret:

    POST https://api.peptidesdirect.io/oauth/register
    Content-Type: application/json

    {
      "client_name": "Your agent's name",
      "redirect_uris": ["https://your-app.example/callback"]
    }

The response's `client_id` is what you send to the authorization endpoint below.
This is a public client (`token_endpoint_auth_method: "none"`): authenticate the
token exchange with PKCE, not a client secret. Only `code_challenge_method: S256`
is supported.

## How to authorize

1. Send the customer's browser to `authorization_endpoint` (see metadata below)
   with `response_type=code`, your `client_id`, a registered `redirect_uri`,
   `code_challenge` + `code_challenge_method=S256`, and an optional `state`.
2. The customer signs in (if not already) and approves or denies the request on
   peptidesdirect.io.
3. On approval, the browser is redirected to your `redirect_uri` with a `code`.
4. Exchange the code at `token_endpoint` with your `code_verifier` for an access
   token (1 hour, JWT, RS256) and a refresh token (30 days, rotating).
5. Use the `refresh_token` grant at `token_endpoint` to get a new access token
   once the old one expires; call `revocation_endpoint` when you no longer need
   access.

Do not probe `POST /oauth/authorize/decision` or any other write endpoint during
passive discovery: registration and authorization only happen with an interactive,
consenting customer. Rely on the public documents below instead.

## Metadata

- Authorization Server Metadata (RFC 8414):
  <https://peptidesdirect.io/.well-known/oauth-authorization-server>
- Protected Resource Metadata (RFC 9728) for the account MCP:
  <https://peptidesdirect.io/.well-known/oauth-protected-resource/mcp/account>

```yaml
agent_auth:
  - skill: peptidesdirect-customer-account
    register_uri: https://api.peptidesdirect.io/oauth/register
    method: RFC 7591 dynamic client registration, public client (no secret), PKCE S256 required
```

Questions: support@peptidesdirect.io