scholarnest API Documentation

Complete REST API reference for scholarnest Student Platform

Base URL: https://scholarnest.codessol.com//api Version: 1.0

API Overview

Base Information

Base URL:
https://scholarnest.codessol.com/api
Authentication:
Bearer Token (Sanctum)
Content-Type:
application/json
GET

API Root Endpoint

Public
GET https://scholarnest.codessol.com/api/

Response (Success - 200)

{
    "message": "scholarnest API",
    "version": "1.0",
    "features": [
        "email_registration",
        "social_login",
        "otp_verification",
        "password_reset"
    ],
    "social_providers": ["google", "facebook"],
    "docs": "http://scholarnest.codessol.com/docs"
}
GET

Get Authenticated User

Protected
GET https://scholarnest.codessol.com/api/user

Headers

Authorization: Bearer {access_token}

Response (Success - 200)

{
    "id": 1,
    "name": "Atta Ullah",
    "email": "attaullahmk099@gmail.com",
    "email_verified_at": "2024-01-15T10:30:00.000000Z",
    "created_at": "2024-01-15T10:25:00.000000Z",
    "updated_at": "2024-01-15T10:25:00.000000Z"
}

Authentication API

Endpoints for user registration, login, OTP verification, and password management.

POST

Register User

Public
POST https://scholarnest.codessol.com/api/auth/register

Request Body

{
    "f_name": "Atta",
    "l_name": "ullah",
    "email": "attaullahmk099@gmail.com",
    "password": "password123",
    "password_confirmation": "password123"
}

Response (Success - 201)

{
    "status": "success",
    "message": "User registered successfully. Please verify your email.",
    "user": {
        "id": 1,
        "f_name": "Atta",
        "l_name": "ullah",
        "email": "attaullahmk099@gmail.com",
        "role": "student",
        "has_password": true,
        "provider": null
    },
    "access_token": "1|abc123def456...",
    "token_type": "Bearer"
}

After registration, an OTP will be sent to the user's email for verification.

POST

Verify OTP

Public
POST https://scholarnest.codessol.com/api/auth/verify-otp

Request Body

{
    "email": "attaullahmk099@gmail.com",
    "otp_code": "123456"
}

Response (Success - 200)

{
    "status": "success",
    "message": "Email verified successfully"
}
POST

Resend OTP

Public
POST https://scholarnest.codessol.com/api/auth/resend-otp

Request Body

{
    "email": "attaullahmk099@gmail.com"
}

Response (Success - 200)

{
    "status": "success",
    "message": "OTP resent successfully"
}
POST

Login

Public
POST https://scholarnest.codessol.com/api/auth/login

Request Body

{
    "email": "attaullahmk099@gmail.com",
    "password": "password123"
}

Response (Success - 200)

{
    "status": "success",
    "message": "Login successful",
    "user": {
        "id": 1,
        "name": "Atta Ullah",
        "email": "attaullahmk099@gmail.com",
        "avatar": null,
        "role": "student",
        "has_password": true,
        "provider": null
    },
    "access_token": "2|def456ghi789...",
    "token_type": "Bearer"
}
POST

Forgot Password

Public
POST https://scholarnest.codessol.com/api/auth/forgot-password

Request Body

{
    "email": "attaullahmk099@gmail.com"
}

Response (Success - 200)

{
    "status": "success",
    "message": "Password reset OTP sent to your email"
}
POST

Reset Password

Public
POST https://scholarnest.codessol.com/api/auth/reset-password

Request Body

{
    "email": "attaullahmk099@gmail.com",
    "otp_code": "123456",
    "password": "newpassword123",
    "password_confirmation": "newpassword123"
}

Response (Success - 200)

{
    "status": "success",
    "message": "Password reset successfully"
}
POST

Refresh Token

Public
POST https://scholarnest.codessol.com/api/auth/refresh-token

Request Headers

Authorization: Bearer {refresh_token}

Response (Success - 200)

{
    "status": "success",
    "access_token": "3|hij789klm012...",
    "token_type": "Bearer",
    "expires_in": 3600
}
POST

Logout

Protected
POST https://scholarnest.codessol.com/api/auth/logout

Headers

Authorization: Bearer {access_token}

Response (Success - 200)

{
    "status": "success",
    "message": "Logged out successfully"
}
POST

Logout All Devices

Protected
POST https://scholarnest.codessol.com/api/auth/logoutAll

Headers

Authorization: Bearer {access_token}

Response (Success - 200)

{
    "status": "success",
    "message": "Logged out from all devices successfully"
}

Profile Management

Endpoints for managing user profile information. All endpoints require authentication.

GET

Get Profile

Protected
GET https://scholarnest.codessol.com/api/profile

Headers

Authorization: Bearer {access_token}

Response (Success - 200)

{
    "status": "success",
    "user": {
        "id": 1,
        "name": "Atta Ullah",
        "email": "attaullahmk099@gmail.com",
        "avatar": null,
        "role": "student",
        "provider": null,
        "has_password": true,
        "email_verified_at": "2024-01-15T10:30:00.000000Z",
        "created_at": "2024-01-15T10:25:00.000000Z"
    }
}
PUT

Update Profile

Protected
PUT https://scholarnest.codessol.com/api/profile/update

Headers

Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
    "name": "Atta Ullah Updated",
    "avatar": "https://example.com/avatar.jpg"
}

Response (Success - 200)

{
    "status": "success",
    "message": "Profile updated successfully",
    "user": {
        "id": 1,
        "name": "Atta Ullah Updated",
        "email": "attaullahmk099@gmail.com",
        "avatar": "https://example.com/avatar.jpg",
        "role": "student",
        "provider": null
    }
}
POST

Change Password

Protected
POST https://scholarnest.codessol.com/api/profile/change-password

Headers

Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
    "current_password": "oldpassword123",
    "password": "newpassword123",
    "password_confirmation": "newpassword123"
}

Response (Success - 200)

{
    "status": "success",
    "message": "Password changed successfully"
}
POST

Set Password (For Social Users)

Protected
POST https://scholarnest.codessol.com/api/auth/set-password

Headers

Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
    "password": "newpassword123",
    "password_confirmation": "newpassword123"
}

Response (Success - 200)

{
    "status": "success",
    "message": "Password set successfully"
}

This endpoint is primarily for users who registered via social login and want to set a password for email/password login.

Social Authentication

Endpoints for social login with Google and Facebook.

GET

Social Login Redirect

Public
GET https://scholarnest.codessol.com/api/auth/{provider}/redirect

Parameters

{provider} - Social provider (google or facebook)

This endpoint redirects users to the social provider's authentication page.

GET

Social Login Callback

Public
GET https://scholarnest.codessol.com/api/auth/{provider}/callback

Parameters

{provider} - Social provider (google or facebook)
Note: This endpoint handles the OAuth callback from social providers. It will return a JSON response with user data and access token.

Response (Success - 200)

{
    "status": "success",
    "message": "Social login successful",
    "user": {
        "id": 2,
        "name": "John Doe",
        "email": "johndoe@gmail.com",
        "avatar": "https://lh3.googleusercontent.com/...",
        "role": "student",
        "has_password": false,
        "provider": "google"
    },
    "access_token": "4|nop345qrs678...",
    "token_type": "Bearer"
}
POST

Link Social Account

Protected
POST https://scholarnest.codessol.com/api/social/link/{provider}

Headers

Authorization: Bearer {access_token}

Parameters

{provider} - Social provider (google or facebook)

Response (Success - 200)

{
    "status": "success",
    "message": "Social account linked successfully",
    "user": {
        "id": 1,
        "name": "Atta Ullah",
        "email": "attaullahmk099@gmail.com",
        "provider": "google,email"
    }
}

Users can link multiple social accounts to their primary email account.

POST

Unlink Social Account

Protected
POST https://scholarnest.codessol.com/api/social/unlink

Headers

Authorization: Bearer {access_token}

Request Body

{
    "provider": "google"
}

Response (Success - 200)

{
    "status": "success",
    "message": "Social account unlinked successfully",
    "user": {
        "id": 1,
        "name": "Atta Ullah",
        "email": "attaullahmk099@gmail.com",
        "provider": "email"
    }
}

Users cannot unlink their last authentication method. They must have at least one authentication method (email/password or social).