Escore Auth Service

OAuth2 Authentication Microservice for the Escore Ecosystem

https://auth.escore.live

📋 Table of Contents

🚀 Overview

The Escore Auth Service is a centralized OAuth2 authentication microservice that provides user authentication and child user management functionality for other applications in the Escore ecosystem.

🔐 OAuth2 Authentication

Full OAuth2 server implementation using Laravel Passport with JWT tokens.

👥 Child User Management

Create child users without email, assign emails later for independent login.

🔗 API-First Design

RESTful API endpoints designed for easy integration with other services.

🔑 Authentication

For protected endpoints, include the authorization header:

Authorization: Bearer {access_token}
Base URL: https://auth.escore.live/api

👤 User Profile Fields

All user objects include the following optional profile fields:

🌐 Public Endpoints

These endpoints do not require authentication:

POST /api/register

Register a new user

Request body:

{
  "name": "John",
  "surname": "Doe",
  "email": "john@example.com",
  "password": "password123",
  "password_confirmation": "password123",
  "birth_year": 1990,
  "birth_date": "1990-05-15",
  "gender": "male",
  "country_code": "US"
}

Note: Profile fields (surname, birth_year, birth_date, gender, country_code) are optional

Response:

{
  "message": "User registered successfully",
  "user": {
    "id": 1,
    "name": "John",
    "surname": "Doe",
    "email": "john@example.com",
    "is_child_user": false,
    "can_login": true,
    "birth_year": 1990,
    "birth_date": "1990-05-15",
    "gender": "male",
    "country_code": "US",
    "created_at": "2025-06-10T17:30:00.000000Z"
  },
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer"
}
POST /api/login

Authenticate user and receive access token

Request body:

{
  "email": "john@example.com",
  "password": "password123"
}

Response:

{
  "message": "Login successful",
  "user": {
    "id": 1,
    "name": "John",
    "surname": "Doe",
    "email": "john@example.com",
    "is_child_user": false,
    "can_login": true,
    "birth_year": 1990,
    "birth_date": "1990-05-15",
    "gender": "male",
    "country_code": "US"
  },
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer"
}
GET /api/health

Service health check

Response: Service status and timestamp

GET /api/public/user/{id}

Get user information by ID For other services

Response: User object with relationships

POST /api/public/verify-user-access

Verify if user can access resources For other services

Request body: user_id

Response: Access status and user information

🔐 Password Reset

Secure password reset functionality with email verification:

POST /api/password/forgot

Request password reset link

Request body:

{
  "email": "user@example.com",
  "tenant_name": "My Application",
  "redirect_url": "https://myapp.com/reset-password"
}

Note: tenant_name and redirect_url are optional

Response:

{
  "message": "If the email address exists in our system, you will receive a password reset link shortly."
}

Rate Limiting: 5 requests/minute + 3 requests per 15 minutes per email/IP

POST /api/password/reset

Reset password using token from email

Request body:

{
  "token": "reset_token_from_email",
  "email": "user@example.com",
  "password": "NewSecurePassword123!",
  "password_confirmation": "NewSecurePassword123!"
}

Response:

{
  "message": "Password has been reset successfully. Please log in with your new password."
}

Rate Limiting: 3 requests/minute + 3 requests per 15 minutes per email/IP

POST /api/password/validate-token

Validate if reset token is still valid

Request body:

{
  "token": "reset_token_from_email",
  "email": "user@example.com"
}

Response:

{
  "message": "Token is valid.",
  "user": {
    "name": "John Doe",
    "email": "user@example.com"
  }
}

Rate Limiting: 10 requests/minute

🔐 Password Reset Security Features

🔗 Integration Example

Basic JavaScript integration:

// Request password reset
const response = await fetch('/api/password/forgot', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        email: 'user@example.com',
        tenant_name: 'My App'
    })
});

// Reset password with token from email
const resetResponse = await fetch('/api/password/reset', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        token: tokenFromEmail,
        email: 'user@example.com',
        password: 'NewPassword123!',
        password_confirmation: 'NewPassword123!'
    })
});

🔒 Protected Endpoints

These endpoints require authentication (Bearer token):

Authentication Management

GET /api/user

Get current authenticated user

Response:

{
  "user": {
    "id": 1,
    "name": "John",
    "surname": "Doe",
    "email": "john@example.com",
    "is_child_user": false,
    "can_login": true,
    "birth_year": 1990,
    "birth_date": "1990-05-15",
    "gender": "male",
    "country_code": "US",
    "parent": null,
    "children": [
      {
        "id": 2,
        "name": "Emma",
        "surname": "Doe",
        "email": null,
        "is_child_user": true,
        "can_login": false,
        "birth_year": 2010,
        "birth_date": "2010-08-20",
        "gender": "female",
        "country_code": "US"
      }
    ]
  }
}
POST /api/logout

Logout and revoke token

Response: Confirmation message

POST /api/refresh

Refresh access token

Response: New access token

GET /api/verify

Verify token validity

Response: Token status and user information

GET /api/profile

Get user profile with relationships

Response: Complete user profile

PUT /api/profile

Update authenticated user's profile

Request body:

{
  "name": "John",
  "surname": "Smith",
  "email": "john.smith@example.com",
  "birth_year": 1985,
  "birth_date": "1985-03-20",
  "gender": "male",
  "country_code": "CA",
  "password": "newpassword123",
  "password_confirmation": "newpassword123"
}

Note: All fields are optional - only provide fields you want to update

Response:

{
  "message": "Profile updated successfully",
  "user": {
    "id": 1,
    "name": "John",
    "surname": "Smith",
    "email": "john.smith@example.com",
    "is_child_user": false,
    "can_login": true,
    "birth_year": 1985,
    "birth_date": "1985-03-20",
    "gender": "male",
    "country_code": "CA",
    "created_at": "2025-06-10T17:30:00.000000Z",
    "parent": null,
    "children": []
  }
}

👶 Child User Management

Manage child users with parent-child relationships:

GET /api/children

Get all child users for the authenticated user

Response: Array of child user objects

POST /api/children

Create a new child user without email

Request body:

{
  "name": "Emma",
  "surname": "Doe",
  "birth_year": 2010,
  "birth_date": "2010-08-20",
  "gender": "female",
  "country_code": "US"
}

Note: All fields except 'name' are optional

Response:

{
  "message": "Child user created successfully",
  "child": {
    "id": 2,
    "name": "Child User Name",
    "email": null,
    "is_child_user": true,
    "can_login": false,
    "birth_year": 2010,
    "birth_date": "2010-08-20",
    "gender": "female",
    "country_code": "US",
    "parent_id": 1
  }
}
PUT /api/children/{id}/assign-email

Assign email to child user and enable login

Request body: email, password, password_confirmation

Response: Updated child user object (can now login)

PUT /api/children/{id}

Update child user information

Request body:

{
  "name": "Emma",
  "surname": "Johnson",
  "can_login": true,
  "birth_year": 2010,
  "birth_date": "2010-08-20",
  "gender": "female",
  "country_code": "US"
}

Note: All fields are optional

Response:

{
  "message": "Child user updated successfully",
  "child": {
    "id": 2,
    "name": "Updated Child Name",
    "email": "child@example.com",
    "is_child_user": true,
    "can_login": true,
    "birth_year": 2010,
    "birth_date": "2010-08-20",
    "gender": "female",
    "country_code": "US",
    "parent_id": 1
  }
}
DELETE /api/children/{id}

Delete a child user

Response: Confirmation message

Child User Workflow

  1. Parent creates child user (no email required, can_login = false)
  2. Later assigns email/password to child user
  3. Child can then login independently with their own credentials
  4. Parent maintains management over their child users

🔐 OAuth2 Endpoints

Laravel Passport automatically provides these OAuth2 endpoints:

GET /oauth/authorize

OAuth2 authorization endpoint

POST /oauth/token

OAuth2 token endpoint

GET /oauth/tokens

List user's tokens Requires Auth

DELETE /oauth/tokens/{token-id}

Revoke specific token Requires Auth

⚠️ Error Responses

All endpoints return consistent error responses:

Validation Error (422)

{
  "message": "Validation failed",
  "errors": {
    "email": ["The email field is required."]
  }
}

Authentication Error (401)

{
  "message": "Invalid credentials"
}

Authorization Error (403)

{
  "message": "User is not allowed to login"
}

Not Found Error (404)

{
  "message": "User not found"
}

🚀 Quick Start

Ready to integrate? Check out our Integration Guide for detailed examples and code snippets.

📊 Live Data

View all endpoints in JSON format: Endpoints JSON

💾 Test Service

Check if the service is running: Health Check