# Auth.md — XDesconto Agent Registration

## Overview

XDesconto is a Brazilian deals and coupons aggregator. Our API provides access to offers,
discount coupons, and product searches from major Brazilian stores.

## Authentication

XDesconto uses **OAuth 2.0 with PKCE** (Authorization Code Flow) for user-scoped access
and **Client Credentials** for automated agent access.

### Agent Registration

1. Register your agent at: `https://api.xdesconto.com.br/auth/register`
2. Provide:
   - `client_name`: Name of your agent or application
   - `redirect_uris`: Callback URLs (for user-scoped access)
   - `grant_types`: `["client_credentials"]` for agents
   - `scope`: Space-separated list (e.g. `offers:read coupons:read`)
   - `identity_type`: `email` or `did:web`

### Discovery Endpoints

| Document | URL |
|---|---|
| OpenID Configuration | `https://xdesconto.com.br/.well-known/openid-configuration` |
| OAuth Authorization Server | `https://xdesconto.com.br/.well-known/oauth-authorization-server` |
| OAuth Protected Resource | `https://xdesconto.com.br/.well-known/oauth-protected-resource` |
| MCP Server Card | `https://xdesconto.com.br/.well-known/mcp/server-card.json` |
| Agent Skills | `https://xdesconto.com.br/.well-known/agent-skills/index.json` |
| API Catalog | `https://xdesconto.com.br/.well-known/api-catalog` |

### Supported Scopes

| Scope | Description |
|---|---|
| `offers:read` | Read access to product offers |
| `coupons:read` | Read access to discount coupons |
| `openid` | OpenID Connect identity |
| `profile` | Basic profile information |
| `email` | Email address |

### Token Endpoint

```
POST https://api.xdesconto.com.br/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=offers:read coupons:read
```

### Revocation

To revoke credentials: `POST https://api.xdesconto.com.br/auth/revoke`

## Rate Limits

- Unauthenticated: 30 requests/minute
- Authenticated agents: 300 requests/minute

## Contact

- Documentation: `https://api.xdesconto.com.br/docs`
- Support: `https://xdesconto.com.br/contato`