# OAuth 2.0 Integration Guide

This document details how to integrate with the Centralized Account System using standard OAuth 2.0 protocols. It is designed for third-party developers building applications that need to authenticate users and access their profile data.

## 1. Overview
Our implementation follows the **Authorization Code Grant** flow, which is the most secure method for server-side applications.

**Base URL**: `https://mauryan.co.in/` (Change this to your actual domain in production)

### Key Endpoints
| Endpoint | Method | Description |
| :--- | :--- | :--- |
| `/oauth.php` | `GET` | **Authorization Endpoint**. Redirect users here to start login. |
| `/api.php?action=token` | `POST` | **Token Endpoint**. Exchange authorization code for an access token. |
| `/api.php?action=userinfo` | `GET` | **Resource Endpoint**. Fetch user profile validation. |

---

## 2. Authentication Flow

### Step 1: Redirect User for Authorization
Redirect your user to our authorization endpoint with your App ID and Redirect URI.

**GET Request**:
```http
GET /oauth.php?response_type=code&client_id={YOUR_APP_ID}&redirect_uri={YOUR_ENCODED_REDIRECT_URI}&state={RANDOM_STRING}
```

- `client_id`: Your unique App ID (Admin assigned).
- `redirect_uri`: Where we should send the user back after login. Must match your registered URI.
- `state`: A random string to prevent CSRF attacks.

### Step 2: Handle the Callback
If the user approves, we will redirect them back to your `redirect_uri` with a temporary `code`.

**Callback URL Example**:
```
https://yourapp.com/callback?code=a1b2c3d4e5f6...&state={YOUR_STATE}
```

> **Important**: Verify the `state` parameter matches what you sent in Step 1.

### Step 3: Exchange Code for Access Token
Your server must now swap this short-lived `code` for a long-lived `access_token`. This request happens strictly server-to-server.

**POST Request to `/api.php`**:
- **Header**: `Content-Type: application/x-www-form-urlencoded`
- **Body**:
    - `action`: `token`
    - `grant_type`: `authorization_code`
    - `code`: The code you received in Step 2.
    - `client_id`: Your App ID.
    - `client_secret`: Your App Secret (Keep this safe!).
    - `redirect_uri`: The same URI used in Step 1.

**Response (JSON)**:
```json
{
    "access_token": "de6780...",
    "expires_in": 3600,
    "token_type": "Bearer"
}
```

### Step 4: Access Protected Resources
Now you can use the `access_token` to fetch user data.

**GET Request to `/api.php`**:
- **Header**: `Authorization: Bearer {YOUR_ACCESS_TOKEN}`
- **Query Param**: `action=userinfo`

**Response (JSON)**:
```json
{
    "sub": 123,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "picture": "https://...",
    "email_verified": true
}
```

---

## 3. Reference Implementation (PHP)
Below is a simplified example of how a client application (`v_oauth.php`) handles this flow using cURL.

### Authorization Link
```php
$params = [
    'response_type' => 'code',
    'client_id'     => 'YOUR_APP_ID',
    'redirect_uri'  => 'YOUR_CALLBACK_URL',
    'state'         => bin2hex(random_bytes(16))
];
$loginUrl = "https://mauryan.co.in//oauth.php?" . http_build_query($params);
// Redirect user to $loginUrl
```

### Exchanging Code (Server-Side)
```php
function getAccessToken($code) {
    $url = 'https://mauryan.co.in//api.php';
    
    $postData = [
        'action'       => 'token',
        'grant_type'   => 'authorization_code',
        'code'         => $code,
        'client_id'    => 'YOUR_APP_ID',
        'client_secret'=> 'YOUR_APP_SECRET',
        'redirect_uri' => 'YOUR_CALLBACK_URL'
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
    
    $response = curl_exec($ch);
    return json_decode($response, true);
}
```

### Fetching User Data
```php
function getUserInfo($accessToken) {
    $url = 'https://mauryan.co.in//api.php?action=userinfo';
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $accessToken"
    ]);
    
    $response = curl_exec($ch);
    return json_decode($response, true);
}
```

---

## 4. Error Handling
The API returns standard HTTP status codes and JSON error objects.

| Status | Error | Description |
| :--- | :--- | :--- |
| `400` | `invalid_request` | Missing parameter or unsupported grant type. |
| `401` | `invalid_client` | Client authentication failed (bad ID/Secret). |
| `400` | `invalid_grant` | The authorization code is invalid or expired. |

**Example Error Response**:
```json
{
    "error": "invalid_grant",
    "error_description": "Authorization code has expired"
}
```