# auth.md

QuiqVeg permits user-authorized agents to obtain a revocable customer bearer session through a WhatsApp OTP exchange. The resource server is `https://api.quiqveg.com` and the human-facing service is `https://quiqveg.com`.

This service supports an anonymous, public-catalog-only credential and one customer grant: `urn:quiqveg:params:oauth:grant-type:whatsapp-otp`. It does not support verified-email, third-party identity-assertion, client-credentials, refresh-token, or privileged-role registration.

## Agent audience

- Public catalog agents may call the read-only endpoints in [the OpenAPI description](https://api.quiqveg.com/openapi.json) without registration, or obtain a short-lived anonymous credential for explicit agent identity.
- User-directed agents may establish a customer session only while the customer actively controls the WhatsApp phone number and supplies the OTP.
- Store, delivery, manager, and admin identities cannot self-register. They must already be provisioned and active for the requested role.
- Passive discovery and security scanners must not call the POST endpoints below because doing so sends a WhatsApp message and can create a customer account after verification.

## Machine-readable summary

```yaml
agent_auth:
  skill: https://quiqveg.com/auth.md
  audience: user_authorized_agents
  oauth_metadata_available: true
  protected_resource_metadata: https://quiqveg.com/.well-known/oauth-protected-resource
  authorization_server_metadata: https://api.quiqveg.com/.well-known/oauth-authorization-server
  authorization_endpoint: https://api.quiqveg.com/agent/auth
  jwks_uri: https://api.quiqveg.com/.well-known/jwks.json
  register_uri: https://api.quiqveg.com/agent/auth
  complete_uri: https://api.quiqveg.com/agent/token
  session_uri: https://api.quiqveg.com/auth/me
  revoke_uri: https://api.quiqveg.com/agent/revoke
  registration_methods:
    - type: anonymous
      claim_uri: https://api.quiqveg.com/agent/auth
      credential_type: access_token
      scope: quiqveg:public-catalog
    - type: user_claimed_whatsapp_otp
      credential_type: access_token
      role: user
```

## Registration method: anonymous public catalog

This optional credential lasts one hour and grants only `quiqveg:public-catalog`. It cannot read or modify profiles, addresses, carts, orders, payments, inventory, or role dashboards. The catalog endpoints remain usable without credentials.

```http
POST https://api.quiqveg.com/agent/auth
Content-Type: application/json

{"type":"anonymous"}
```

The response contains `access_token`, `token_type`, `expires_in`, and `scope`. Send it as an `Authorization: Bearer` header or discard it when public access is sufficient.

## Registration method: user-claimed WhatsApp OTP

This is the only supported agent provisioning method. The user must authorize every registration and communicate the OTP to the agent. Do not scrape messages, query internal storage, or attempt to bypass OTP rate limits.

### 1. Request an OTP

```http
POST https://api.quiqveg.com/agent/auth
Content-Type: application/json

{"phone":"91XXXXXXXXXX"}
```

The phone may be supplied as a 10-digit Indian number or in normalized `91XXXXXXXXXX` form. A successful response is HTTP 200 and the OTP is sent to that phone through WhatsApp. HTTP 429 includes `Retry-After`; wait for that duration and do not loop.

### 2. Ask the user for the OTP

The user reads the six-digit OTP from WhatsApp and intentionally supplies it to the agent. The OTP expires after 10 minutes and has a bounded verification-attempt count. Never log, persist, replay, or expose the OTP.

### 3. Complete provisioning

```http
POST https://api.quiqveg.com/agent/token
Content-Type: application/json

{"grant_type":"urn:quiqveg:params:oauth:grant-type:whatsapp-otp","phone":"91XXXXXXXXXX","otp":"123456"}
```

Successful verification creates the customer identity when necessary and returns a standard bearer response containing `access_token`, `token_type`, `expires_in`, and `scope`. Keep the token in protected memory and never expose it to logs, URLs, browser storage, or another user.

### 4. Use and verify the session

Return the issued token only to `https://api.quiqveg.com`:

```http
GET https://api.quiqveg.com/auth/me
Authorization: Bearer <access_token>
```

Protected requests use the same header. Permissions and region access are enforced by each endpoint; this grant always resolves to the customer role and cannot obtain store, delivery, manager, or admin access. The single advertised scope is `quiqveg:user`.

### 5. End the session

```http
POST https://api.quiqveg.com/agent/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_token>&token_type_hint=access_token
```

The endpoint is idempotent and returns HTTP 200 even when the token is already invalid. Discard the local token after revocation. Do not share a session between people, devices, roles, origins, or agent users.

## Errors and safe recovery

| Status | Meaning | Agent action |
| --- | --- | --- |
| 400 | Invalid phone, OTP, or expired OTP | Correct the input or restart once with user consent. |
| 401 | Session missing or expired | Stop the protected action and ask the user whether to authenticate again. |
| 403 | Role is unavailable or not provisioned | Stop. Do not retry under another privileged role. |
| 429 | OTP request rate limit | Honor `Retry-After`; do not retry early. |
| 5xx | Temporary service failure | Retry idempotent GET requests with backoff. Ask before repeating an OTP request. |

## Public discovery

- API catalog: https://quiqveg.com/.well-known/api-catalog
- Protected resource metadata: https://quiqveg.com/.well-known/oauth-protected-resource
- Authorization server metadata: https://api.quiqveg.com/.well-known/oauth-authorization-server
- Authorization endpoint description: https://api.quiqveg.com/agent/auth
- JSON Web Key Set: https://api.quiqveg.com/.well-known/jwks.json
- API documentation: https://quiqveg.com/developers/api
- OpenAPI description: https://api.quiqveg.com/openapi.json
- Service status: https://api.quiqveg.com/health