External API access

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. Define API App Role

   Before external systems can be granted access, an App Role must be defined in the API App Registration.

   Go to:

   • Microsoft Entra ID → App registrations

   • Open EGU.PartnerPortal.ApiService

   Navigate to App roles → Create app role.

   Configure the role:

   Field	Value
   Display name	External System Access
   Allowed member types	Applications
   Value	ExternalSystem.Access
   Description	Allows external systems to access turnaround report data

   Save the role.
   
   

2. Create External System App Registration

   • Create a separate application registration for each external company.

     Go to:

     • Microsoft Entra ID → App registrations

     • Select New registration

     Configuration:

     Setting	Value
     Name	{CompanyName}-PartnerPortal-Access
     Supported account types	Accounts in this organizational directory only
     Redirect URI	Leave blank

3. Generate Client Secret

   • 1. Open the newly created PartnerPortal-External-{CompanyName} app.

     2. Navigate to Certificates & secrets.

     3. Click New client secret.

     4. Copy the secret value immediately and store it securely.

     ⚠️ The secret value cannot be viewed again after creation.

     Never commit secrets to source control.
     
     

4. Assign Permissions

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

5. Company Mapping (API side configuration)

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