# Authentication & Registration for AI Agents (Auth.md)

> This document defines authentication, registration, and API access instructions for AI agents, autonomous bots, and automated assistants interacting with **Discve Alumy** on behalf of users.

---

## 1. Overview & Service Metadata

- **Application Name:** Discve Alumy
- **Web Application URL:** https://alumy.pages.dev
- **Purpose:** Student learning dashboard, KSSM SPM curriculum prep, and teen wellness tracking platform.
- **Resource Server:** `https://alumy.pages.dev` / `https://<project-ref>.supabase.co`
- **Authorization Server:** `https://<project-ref>.supabase.co/auth/v1`
- **Supported Auth Schemes:** OAuth 2.0, Bearer JWT, Supabase Session Tokens

---

## 2. Interactive (Web-Based) Agent Registration & Login

If the AI agent operates through a browser session or web automation on behalf of a human student:

### Registration URL
- **Path:** `/signup`
- **Full URL:** `https://alumy.pages.dev/signup`
- **Fields Required:**
  - `email`: Valid student or guardian email address.
  - `password`: Minimum 8 characters.
  - `username`: Unique username (3–20 alphanumeric characters).

### Login URL
- **Path:** `/login`
- **Full URL:** `https://alumy.pages.dev/login`
- **Supported Methods:**
  - Email & Password
  - Google One-Tap / OAuth (`/auth/v1/authorize?provider=google`)

---

## 3. Programmatic Registration (Autonomous Agents)

AI agents registering a new student account programmatically should execute a `POST` request to the Supabase authentication endpoint:

```http
POST https://<project-ref>.supabase.co/auth/v1/signup
Content-Type: application/json
apikey: <SUPABASE_ANON_KEY>

{
  "email": "student@example.com",
  "password": "<secure-password>",
  "data": {
    "username": "student_handle",
    "role": "student"
  }
}
```

### Response
On successful creation, the server returns status `200 OK` with session tokens:

```json
{
  "access_token": "<jwt_access_token>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<refresh_token>",
  "user": {
    "id": "uuid",
    "email": "student@example.com",
    "user_metadata": {
      "username": "student_handle"
    }
  }
}
```

---

## 4. Programmatic Authentication & Token Exchange

To authenticate an existing user on their behalf, perform password grant token exchange:

```http
POST https://<project-ref>.supabase.co/auth/v1/token?grant_type=password
Content-Type: application/json
apikey: <SUPABASE_ANON_KEY>

{
  "email": "student@example.com",
  "password": "<secure-password>"
}
```

### Refreshing Expired Tokens
When an `access_token` expires (default TTL: 3600 seconds):

```http
POST https://<project-ref>.supabase.co/auth/v1/token?grant_type=refresh_token
Content-Type: application/json
apikey: <SUPABASE_ANON_KEY>

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

---

## 5. Authenticated API Usage

All protected resource requests made by the bot must include both the project public key and the user's Bearer token in the request headers:

```http
GET /rest/v1/profiles?id=eq.<user_id> HTTP/1.1
Host: <project-ref>.supabase.co
apikey: <SUPABASE_ANON_KEY>
Authorization: Bearer <access_token>
Content-Type: application/json
```

### Available User Scopes & Resources
- **Student Profile:** `profiles` (read/write owned row)
- **Wellness Check-ins:** `wellness_check_ins` (daily logs: mood, stress, energy, sleep, focus)
- **Learning Progress:** `learning_progress` (course completions, daily quest state, streak data)
- **Learning Quests & Milestones:** `daily_quests` (active challenges and claimed rewards)

---

## 6. Token Revocation & Sign Out

When completing an automated task or logging out:

```http
POST https://<project-ref>.supabase.co/auth/v1/logout
apikey: <SUPABASE_ANON_KEY>
Authorization: Bearer <access_token>
```

---

## 7. Bot Access Policies & Rate Limiting

- **Bot Identification:** Autonomous bots are recommended to declare their agent identity in the `User-Agent` header (e.g. `User-Agent: MyStudentAIAgent/1.0 (+https://example.com/bot)`).
- **Rate Limits:** 60 auth operations per minute per IP address. Synchronous database writes should be throttled to no more than 1 sync every 8 seconds.
- **Privacy & Safety:** Alumy is an educational platform serving secondary school students. Automated agents must not store or exfiltrate private journal entries or personal student identifiable data without explicit user consent.