# Laiqua auth.md

You are an agent. **Laiqua** supports agent discovery and user-delegated access to the cashback API. This document describes how to authenticate; machine-readable metadata lives at `https://laiqua.xyz/.well-known/oauth-protected-resource` and `https://laiqua.xyz/.well-known/oauth-authorization-server`.

- **Resource server (API):** `https://api.laiqua.xyz/api/v1`
- **Authorization server (issuer):** `https://laiqua.xyz`
- **Human docs:** https://laiqua.xyz/docs/api

## Step 1 — Discover

### 1a. Protected Resource Metadata

```http
GET /.well-known/oauth-protected-resource
Host: laiqua.xyz
```

Read `resource`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported` (use `header` for `Authorization: Bearer`).

### 1b. Authorization Server metadata

```http
GET /.well-known/oauth-authorization-server
Host: laiqua.xyz
```

Read `issuer`, `token_endpoint`, `revocation_endpoint`, and the `agent_auth` block (`register_uri`, `claim_uri`, `revocation_uri`, `identity_types_supported`).

## Step 2 — Pick a method

| Situation | Method |
|-----------|--------|
| No user identity yet; public catalog / clicks | **anonymous** |
| User should sign in (Google) | **identity_assertion** + **verified_email** (OAuth) |

Cross-check `agent_auth.identity_types_supported` before proceeding.

## Step 3 — Register

### anonymous

Use a stable anonymous id for public API calls (create client-side or reuse from the Laiqua extension):

```http
GET https://api.laiqua.xyz/api/v1/auth/config
```

Then call public endpoints with header:

```http
X-Anon-Uuid: u_<32-hex-chars>
```

Example: `POST https://api.laiqua.xyz/api/v1/clicks` with product ids. No cookie required for discovery-only traffic.

Credential: treat session-less `X-Anon-Uuid` as the anonymous principal until the user completes OAuth.

### identity_assertion + verified_email (Google OAuth)

Start browser-based registration (authorization code via Google):

```http
GET https://api.laiqua.xyz/api/v1/auth/google
```

The user completes Google sign-in; the service sets HTTP-only cookies and may redirect to `https://laiqua.xyz/dashboard`.

For programmatic clients that already hold a Google ID token (mobile pattern):

```http
POST https://api.laiqua.xyz/api/v1/auth/mobile/google
Content-Type: application/json

{
  "idToken": "<Google ID token>",
  "anonUuid": "u_..."
}
```

## Step 4 — Claim / session

Human claim surface: `https://laiqua.xyz/login` (links to Google OAuth when enabled).

Check session:

```http
GET https://api.laiqua.xyz/api/v1/auth/me
Authorization: Bearer <access_token>
```

(Web clients use cookies; extension sync: `GET https://api.laiqua.xyz/api/v1/auth/extension-sync`.)

## Step 5 — Token

Refresh access (cookie-based web):

```http
POST https://api.laiqua.xyz/api/v1/auth/refresh
```

Mobile refresh:

```http
POST https://api.laiqua.xyz/api/v1/auth/mobile/refresh
Content-Type: application/json

{ "refreshToken": "<refresh_token>" }
```

## Step 6 — Call the API

```http
GET https://api.laiqua.xyz/api/v1/products/catalog?filter=hot
Authorization: Bearer <access_token>
```

Or with anonymous header for unauthenticated catalog access.

## Revocation

```http
POST https://api.laiqua.xyz/api/v1/auth/logout
```

Clears session cookies. Mobile clients discard refresh tokens locally.

## Scopes

| Scope | Use |
|-------|-----|
| `openid` | OpenID Connect via Google |
| `email` | Account email |
| `profile` | Display name / avatar |

## Note on auth.md vs full agent-auth POST

Laiqua does **not** expose `POST /agent/auth` (passive scanners must not probe it). Registration is OAuth 2.0 authorization code at `register_uri` plus optional `X-Anon-Uuid` for anonymous traffic. See `agent_auth` in Authorization Server metadata for the canonical URIs.