Overview

The EGU Partner Portal provides secure external API access for authorized partners to retrieve turnaround report data programmatically using OAuth2 authentication.

How External Access Works

Authentication & Authorization Flow

┌─────────────────┐
│ External System │  1. Request Token
│   (Partner)     │────────────────────┐
└─────────────────┘                    │
                                       v
                              ┌────────────────┐
                              │   Azure AD     │
                              │  Validates:    │
                              │  - Credentials │
                              │  - Role        │
                              └────────┬───────┘
                                       │
                                       │ 2. Issues JWT Token
                                       │    - appid claim
                                       │    - ExternalSystem.Access role
                                       │    - 1 hour expiry
                                       v
┌─────────────────┐
│ External System │  3. Call API with Token
└────────┬────────┘
         │
         v
┌────────────────────────────┐
│  Partner Portal API        │
│                            │
│  ✓ JWT Validation          │
│  ✓ Role Check              │
│  ✓ Route Restriction       │
│  ✓ Company Authorization   │
│                            │
│  → Query Database          │
│  → Return JSON             │
└────────────────────────────┘

Security Layers

1. Authentication: Azure AD validates credentials and issues signed JWT tokens
2. Role Check: Only apps with ExternalSystem.Access role can authenticate
3. Route Restriction: External tokens limited to /api/external/* endpoints
4. Company Authorization: Apps can only access their assigned company data

Authentication

OAuth2 Configuration

Token Request

POST https://login.microsoftonline.com/6073ce8b-73f3-4df4-9b80-5e40cdc6965f/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=1f018c75-2ea9-4d46-a4f1-a45d2d47d043
&client_secret=YOUR_CLIENT_SECRET
&scope=api://4dad5d62-dc8c-4378-8bd0-ae736a4d73fe/.default

Response:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci..."
}

Token Lifetime: 1 hour

API Usage (Dev Environment)

Base Configuration

Endpoint: Get Turnaround Report

Retrieves work order turnaround data with status transitions.

GET /turnaround-report

Query Parameters:

Request Example:

GET /api/external/turnaround-report?companyNumber=SonlincXML3&dateFrom=2025-01-01&dateTo=2025-12-31
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGci...
Accept: application/json

Response (200 OK):

{
  "turnaroundReportItems": [
    {
      "workOrderID": 1503,
      "workOrderNumber": "E261503",
      "workOrderTypeID": 1,
      "workOrderType": "New Installation",
      "consumptionCategoryID": 1,
      "consumptionCategoryName": "Apartment",
      "preFuseAmpere": 10,
      "preFuseTypeID": 1,
      "preFuseType": "Switch",
      "workOrderStatusID": 2,
      "workOrderStatus": "Registration Sent",
      "timestamp": "2025-12-20T10:30:00Z"
    }
  ]
}

Response Fields:

HTTP Status Codes:

Validation Rules:

• Date range max 5 years
• dateFrom must be ≤ dateTo

Configuration

Azure AD Setup

1. Create App Registration

   • Name: PartnerPortal-External-{CompanyName}
   • Account type: Single tenant

2. Generate Client Secret

   • Navigate to Certificates & secrets
   • Create new client secret
   • Store securely (never commit to code)

3. Assign Permissions

   • Add permission: EGU.PartnerPortal.ApiService
   • Select: ExternalSystem.Access
   • Grant admin consent

4. Company Mapping (API side configuration)

   {
     "ExternalCompanies": {
       "Ravdex": {
         "AppId": "1f018c75-2ea9-4d46-a4f1-a45d2d47d043",
         "CompanyNumber": "SonlincXML3",
         "Name": "Ravdex"
       }
     }
   }