# Garden Flowers auth.md

This document specifies authentication, authorization, and registration procedures for autonomous AI agents interacting with the Garden Flowers API at `https://gardenflowers.ae/api/v1`.

## 0. Quickstart (order flowers in 3 steps)

```bash
# 1) Browse the catalog (public, no auth)
curl https://gardenflowers.ae/api/v1/products

# 2) Inspect one product + variants
curl https://gardenflowers.ae/api/v1/products/santorini

# 3) Create an order → receive a Stripe payment_url in AED
curl -X POST https://gardenflowers.ae/api/v1/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_agent_token>" \
  -d '{
    "items": [{ "slug": "santorini", "qty": 1 }],
    "customer": { "name": "Agent Bot", "phone": "+971500000000" },
    "delivery": { "address": "Downtown Dubai", "date": "2026-08-01" }
  }'
# → { "payment_url": "https://...", "order_id": 1234 }

# 4) Confirm payment status after the Stripe redirect
curl https://gardenflowers.ae/api/v1/orders/1234/verify-payment
# → { "status": "paid", "order_id": 1234 }
```

Public catalog reads (`GET /products`, `GET /products/{slug}`, `GET /categories`) need **no authentication**. Only `POST /checkout` requires a Bearer token with the `orders:write` scope (see section 4). Full human-readable guide: https://gardenflowers.ae/agent-commerce/

## 1. Overview & Audience

Garden Flowers provides signature floristry, bouquet ordering, and express delivery services across Dubai and the UAE. AI agents can discover catalog offerings, check item availability, create draft orders, and manage checkout sessions.

## 2. Agent Registration Endpoint

- **Registration URI**: `https://gardenflowers.ae/api/agent/register`
- **Supported Identity Types**:
  - `identity_assertion` (`urn:ietf:params:oauth:token-type:id-jag`, `verified_email`)
  - `anonymous` (Ephemeral session tokens)

### Registration Request Example

```json
{
  "agent_name": "FlowerAssistantBot",
  "identity_type": "anonymous",
  "capabilities": ["catalog_search", "order_creation"]
}
```

## 3. OAuth & Token Authentication

- **Authorization Server**: `https://gardenflowers.ae/.well-known/oauth-authorization-server`
- **Protected Resource Metadata**: `https://gardenflowers.ae/.well-known/oauth-protected-resource`
- **Token Endpoint**: `https://gardenflowers.ae/oauth/token`

Include the issued Bearer token in all HTTP requests:

```http
Authorization: Bearer <your_agent_token>
```

### Token response example

A successful token request returns:

```json
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "scope": "orders:write catalog:read",
  "expires_in": 3600
}
```

Agents should cache the token until `expires_in` elapses, then request a new one.

## 4. Supported Scopes

- `catalog:read` — Search products, browse flower categories, check pricing and stock.
- `orders:read` — Read order status and tracking details.
- `orders:write` — Create draft orders and initialize checkout flows.