# gigglefone.fr auth.md

> Agent registration and credential use for **Giggle Fone** storefront APIs and MCP/ACP tools.
> This origin publishes OAuth Authorization Server metadata and Protected Resource Metadata.

## Audience

AI agents, developer automations, and MCP/ACP clients that need to call **authenticated**
Giggle Fone B2C tools (cart, orders, API-key management, etc.). Public catalog tools and
`/api/ai/*` discovery endpoints do **not** require registration.

## Supported methods

| Method | How |
|--------|-----|
| **OAuth 2.1 (authorization code + PKCE)** | Discover `https://gigglefone.fr/.well-known/oauth-authorization-server`; authorize at `/oauth/authorize`; exchange at `/oauth/token`. Access tokens are **B2C API keys** accepted as `Authorization: Bearer` / `X-Api-Key` on MCP/ACP. Optional OpenID `id_token` (RS256) via `/oauth/jwks`. |
| **API key (Bearer)** | Create while logged into the storefront dashboard; send `Authorization: Bearer <api_key>` (or `X-Api-Key`) on MCP/ACP calls |
| **Session JWT** | Human login via email/password or Google/Facebook social → httpOnly session cookie / access JWT for browser and proxied Nitro routes |

Unsupported:

- Resource Owner Password Credentials
- Client credentials without a human consent step
- Using Google/Facebook IdP tokens directly as resource access tokens

## OAuth discovery

| Document | URL |
|----------|-----|
| Authorization Server (RFC 8414) | https://gigglefone.fr/.well-known/oauth-authorization-server |
| OpenID configuration (alias) | https://gigglefone.fr/.well-known/openid-configuration |
| Protected Resource (RFC 9728) | https://gigglefone.fr/.well-known/oauth-protected-resource |
| JWKS | https://gigglefone.fr/oauth/jwks |

`authorization_servers` in Protected Resource Metadata lists `https://gigglefone.fr/`.

The Authorization Server metadata includes an `agent_auth` block:

| Field | Value |
|-------|-------|
| `skill` | https://gigglefone.fr/auth.md |
| `register_uri` | https://gigglefone.fr/oauth/authorize |
| `revocation_uri` | https://gigglefone.fr/oauth/revoke |
| `identity_types_supported` | `["user_consent_authorization_code"]` |
| `credential_types_supported` | `["access_token", "api_key"]` |

Unsupported today: ID-JAG identity assertion and anonymous claim ceremonies (see `agent_auth.unsupported_flows`).

### Agent OAuth flow (register)

1. Read AS metadata (`https://gigglefone.fr/.well-known/oauth-authorization-server`); use `agent_auth.register_uri` as the human-consent entry.
2. Register as a **public** client (`token_endpoint_auth_methods_supported: none`). No Dynamic Client Registration — choose a stable `client_id` string.
3. Generate PKCE (`S256`).

```http
GET /oauth/authorize?response_type=code&client_id=AGENT_CLIENT&redirect_uri=https://127.0.0.1:8765/callback&scope=openid%20api%20offline_access&code_challenge=PKCE_S256_CHALLENGE&code_challenge_method=S256&state=STATE HTTP/1.1
Host: gigglefone.fr
```

4. Human signs in (if needed) and approves on `https://gigglefone.fr/oauth/consent`.
5. Exchange `code` + `code_verifier` at the token endpoint:

```http
POST /oauth/token HTTP/1.1
Host: gigglefone.fr
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https://127.0.0.1:8765/callback&client_id=AGENT_CLIENT&code_verifier=PKCE_VERIFIER
```

6. Call MCP/ACP with `Authorization: Bearer <access_token>` (the access token is a B2C API key).
7. Revoke refresh tokens when done:

```http
POST /oauth/revoke HTTP/1.1
Host: gigglefone.fr
Content-Type: application/json

{"token":"REFRESH_TOKEN"}
```

## Registration / provisioning (API keys)

Alternative to OAuth when a human already has a dashboard session:

1. Create a shopper (or partner) account on https://gigglefone.fr/ (locale-prefixed signup).
2. Sign in, open **Dashboard → Settings → API keys** (`https://gigglefone.fr/…/dashboard/settings/api-keys`).
3. Create a key:

```http
POST /api/auth/api-keys HTTP/1.1
Host: gigglefone.fr
Content-Type: application/json
Cookie: <authenticated session>

{"name":"agent-key"}
```

The plaintext key is shown **once**. Revoke via the dashboard or:

```http
DELETE /api/auth/api-keys/{id} HTTP/1.1
Host: gigglefone.fr
Cookie: <authenticated session>
```

Equivalent MCP tools (require an existing user session / token first): `create_api_key`,
`list_api_keys`, `delete_api_key`.

## Credential use

| Surface | Auth |
|---------|------|
| Public AI catalog | `GET https://gigglefone.fr/api/ai/catalog`, `GET https://gigglefone.fr/api/ai/devices` — no auth |
| MCP Streamable HTTP | See `/.well-known/mcp/server-card.json` `transport.endpoint`; production often requires Bearer / API key |
| ACP REST | `GET/POST https://gigglefone.fr/acp/…` with `Authorization` or `X-Api-Key` |
| A2A JSON-RPC | `POST https://gigglefone.fr/a2a` — public catalog guidance is unauthenticated; privileged skills need API key |

Do **not** send Google or Facebook IdP tokens as resource access tokens to our APIs — those
providers only feed the browser social-login exchange.

## Related discovery

| Doc | URL |
|-----|-----|
| This file | https://gigglefone.fr/auth.md |
| llms.txt | https://gigglefone.fr/llms.txt |
| Agent skills | https://gigglefone.fr/.well-known/agent-skills/index.json |
| MCP Server Card | https://gigglefone.fr/.well-known/mcp/server-card.json |
| A2A Agent Card | https://gigglefone.fr/.well-known/agent-card.json |
| ACP commerce | https://gigglefone.fr/.well-known/acp.json |
| UCP profile | https://gigglefone.fr/.well-known/ucp |
| API catalog | https://gigglefone.fr/.well-known/api-catalog |

## Contact

- Email: service@gigglefone.com
- Phone: +852 5106 6241