TELS Platform Service - API Documentation

🏠 Home › platform / api / docs

TELS Platform Service - API Documentation

Overview

Authentication

JWT Bearer

Standard JWT Bearer token authentication:

Authorization: Bearer <access_token>

Token validation: - Signing: Symmetric key (base64-encoded) from configuration - Issuer: localservices.tels.net (validated) - Audience: services.tels.net (validated) - Lifetime: Validated

Custom Authorization

Persona-based access control: - Reads: DirectSupplyPartner | Customer | Owner - Writes: DirectSupplyPartner only - Diagnostics: Anonymous (health check, ping) or authenticated (database status)

Settings Controller

Route Prefix: /platform/v1 Authorization: JWT Bearer + Persona-based (varies by endpoint)

Method Path Auth Personas Description
GET /platform/v1/settings DirectSupplyPartner Get all settings (paginated)
GET /platform/v1/subsystems/{subsystemName}/settings DSP, Customer, Owner Get subsystem settings (paginated)
GET /platform/v1/subsystems/{subsystemName}/settings/{settingName} DSP, Customer, Owner Get single setting
GET /platform/v1/subsystems/{subsystemName}/settings/{settingName}/value DSP, Customer, Owner Get setting value only
PUT /platform/v1/subsystems/{subsystemName}/settings/{settingName} DirectSupplyPartner Create or update setting
DELETE /platform/v1/subsystems/{subsystemName}/settings/{settingName} DirectSupplyPartner Delete setting

GET /platform/v1/settings

Get all platform settings across all subsystems with pagination.

Authorization: DirectSupplyPartner only

Query Parameters: - pageKey (string, optional) — Pagination cursor from previous response

Response (200 OK):

{
  "settings": [
    {
      "subsystemName": "WorkOrders",
      "settingName": "MaxAttachmentSize",
      "settingValue": 62914560
    },
    {
      "subsystemName": "Notifications",
      "settingName": "EmailTemplates",
      "settingValue": {
        "workOrderCreated": "template-001",
        "workOrderUpdated": "template-002"
      }
    }
  ],
  "nextPageKey": "eyJwYWdlIjoyfQ=="
}

GET /platform/v1/subsystems/{subsystemName}/settings

Get all settings for a specific subsystem with pagination.

Path Parameters: - subsystemName (string, required) — Subsystem identifier (case-insensitive)

Query Parameters: - pageKey (string, optional) — Pagination cursor

Response (200 OK):

{
  "settings": [
    {
      "subsystemName": "WorkOrders",
      "settingName": "MaxAttachmentSize",
      "settingValue": 62914560
    }
  ],
  "nextPageKey": null
}

GET /platform/v1/subsystems/{subsystemName}/settings/{settingName}

Get a single setting by subsystem and setting name.

Path Parameters: - subsystemName (string, required) — Subsystem identifier (case-insensitive) - settingName (string, required) — Setting identifier (case-insensitive)

Response (200 OK):

{
  "subsystemName": "WorkOrders",
  "settingName": "MaxAttachmentSize",
  "settingValue": 62914560
}

GET /platform/v1/subsystems/{subsystemName}/settings/{settingName}/value

Get only the value of a setting (without the wrapper object).

Path Parameters: - subsystemName (string, required) - settingName (string, required)

Response (200 OK):

62914560

Returns the raw JSON value — can be a number, string, object, array, or boolean.

PUT /platform/v1/subsystems/{subsystemName}/settings/{settingName}

Create or update a platform setting. Automatically records an audit entry in the history table.

Authorization: DirectSupplyPartner only

Path Parameters: - subsystemName (string, required) - settingName (string, required)

Request Body:

{
  "settingValue": 62914560
}

settingValue can be any valid JSON value (number, string, object, array, boolean).

Response: 200 OK

Processing: 1. Extracts token claims (person ID, name, persona) for audit 2. Opens transaction with Repeatable Read isolation 3. Calls platform.tfn_setting_m to upsert setting + create history record 4. Commits transaction

DELETE /platform/v1/subsystems/{subsystemName}/settings/{settingName}

Delete a platform setting. Records a delete audit entry in the history table.

Authorization: DirectSupplyPartner only

Path Parameters: - subsystemName (string, required) - settingName (string, required)

Response: 200 OK

Diagnostics Controller

Route Prefix: /platform/v1/diagnostics

Method Path Auth Description
GET /platform/v1/diagnostics/health-check Anonymous Returns 200 OK
GET /platform/v1/diagnostics/ping Anonymous Returns "pong"
GET /platform/v1/diagnostics/database Authenticated Database connectivity status

Key Data Contracts

PlatformSetting

{
  "subsystemName": "WorkOrders",
  "settingName": "MaxAttachmentSize",
  "settingValue": 62914560
}

PutPlatformSettingRequest

{
  "settingValue": 62914560
}

PagedPlatformSettingsResponse

{
  "settings": [],
  "nextPageKey": "cursor-or-null"
}

ScheduledMessageEvent (Event Contract)

{
  "subsystemName": "Customers",
  "messageName": "SyncPreferences",
  "description": "Periodic preference sync",
  "schedule": "0 */6 * * *"
}

Global Response Codes

Code Meaning
200 Success
400 Bad Request — validation error (ProblemDetails)
401 Unauthorized — invalid or missing JWT token
403 Forbidden — insufficient persona
404 Not Found — setting does not exist

Client SDK Usage

Other TELS services consume this API via the TELS.Platform.ClientSdk NuGet package:

// Registration
services.AddTelsPlatformProxies("https://services.tels.net/platform");

// Usage
var setting = await settingsProxy.GetSubsystemSettingValueAsync<int>(
    accessToken, "WorkOrders", "MaxAttachmentSize");

var settingOrDefault = await settingsProxy.GetSubsystemSettingValueOrDefaultAsync<int>(
    accessToken, "WorkOrders", "NonExistent"); // returns null instead of throwing

SDK Features: - Typed generic methods for any JSON-serializable type - OrDefault variants that return null on 404 - Polly retry policy: 5 retries with exponential backoff (max 5 seconds) - ProblemDetails-aware exception handling

Notes