# Authentication & Agent Registration for UPCBay

Welcome AI agents and developers. This document defines the authentication, registration, and programmatic access protocols for UPCBay.

## Overview
UPCBay provides APIs, MCP tools, and checkout endpoints for authentic GS1-originated UPC-A and EAN-13 barcodes.

- **Protected Resource**: `https://upcbay.com/api`
- **OAuth Authorization Server**: `https://upcbay.com/.well-known/oauth-authorization-server`
- **Protected Resource Metadata**: `https://upcbay.com/.well-known/oauth-protected-resource`

---

## Agent Registration Protocol

AI agents can register automatically to acquire scoped credentials:

### 1. Dynamic Client Registration
Send an HTTP POST request to the registration endpoint:
```http
POST /api/auth/register HTTP/1.1
Host: upcbay.com
Content-Type: application/json

{
  "client_name": "MyAiAgent/1.0",
  "grant_types": ["client_credentials", "urn:ietf:params:oauth:grant-type:token-exchange"],
  "redirect_uris": ["https://agent.example.com/oauth/callback"],
  "scope": "barcodes:read barcodes:validate barcodes:purchase"
}
```

**Response**:
```json
{
  "client_id": "agent_upc_live_99a8b7c6d5e4f3a2",
  "client_secret": "sec_live_abcdef1234567890",
  "client_id_issued_at": 1740000000,
  "client_secret_expires_at": 0
}
```

### 2. Obtaining an Access Token
Exchange client credentials for a Bearer JWT:
```http
POST /api/auth/token HTTP/1.1
Host: upcbay.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=agent_upc_live_99a8b7c6d5e4f3a2&client_secret=sec_live_abcdef1234567890&scope=barcodes:validate
```

**Response**:
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "barcodes:validate"
}
```

### 3. API Key Direct Authentication
Alternatively, API Keys generated in the user dashboard or via programmatic claim can be passed via the `Authorization` header:
```http
GET /api/v1/validate/012345678905 HTTP/1.1
Host: upcbay.com
Authorization: Bearer <YOUR_API_KEY>
```

---

## Supported Scopes
| Scope | Description |
|---|---|
| `barcodes:read` | Read public barcode registry information |
| `barcodes:validate` | Run validation and check digit computation algorithms |
| `barcodes:purchase` | Initiate barcode bundle orders and payments |
| `orders:read` | Retrieve order status and barcode file downloads |

---

## Revocation & Token Claim
- **Revocation Endpoint**: `https://upcbay.com/api/auth/revoke`
- **Claim Endpoint**: `https://upcbay.com/api/auth/claim`
- **Public Key JWKS**: `https://upcbay.com/.well-known/jwks.json`