Skip to main content

TS.43 Entitlement Configuration

OmniSEP implements GSMA TS.43 Service Entitlement Configuration, enabling mobile devices to query their service entitlements (VoWiFi, VoLTE, SMS, etc.) from the carrier network.

Overview​

Request Flow​

Initial Authentication (EAP-AKA)​

Fast Re-Authentication (Token)​

HTTP Interface​

Endpoint​

MethodPathContent-Type
GET/Query parameters
POST/application/json

Required Parameters​

ParameterTypeDescription
terminal_idStringDevice IMEI (15 digits)
terminal_vendorStringDevice manufacturer (max 4 chars per RCC.14)
terminal_modelStringDevice model (max 10 chars per RCC.14)
terminal_sw_versionStringSoftware version (max 20 chars per RCC.14)
entitlement_versionStringProtocol version (e.g., "2.0")
appString/ListApplication ID(s) to query

Authentication Parameters​

One of these authentication methods is required:

ParameterDescription
EAP_IDRoot NAI for EAP-AKA: 0<IMSI>@nai.epc.mnc<MNC>.mcc<MCC>.3gppnetwork.org
tokenAuthentication token from previous response
temporary_tokenTemporary token
operator_tokenOperator-issued token

Optional Parameters​

ParameterTypeDescription
IMSIStringRequired with token for fast re-auth
app_nameStringApplication name
app_versionStringApplication version
notif_actionIntegerNotification action (0=disable, 1=GCM, 2=FCM)
notif_tokenStringPush notification token
versIntegerConfiguration version for change detection

Request Examples​

GET with Token:

GET /?terminal_id=123456789012345&terminal_vendor=Goog&terminal_model=Pixel8&terminal_sw_version=14.0&entitlement_version=2.0&app=ap2004&token=abc123&IMSI=310410123456789

POST with EAP-AKA:

{
  "terminal_id": "123456789012345",
  "terminal_vendor": "Goog",
  "terminal_model": "Pixel8",
  "terminal_sw_version": "14.0",
  "entitlement_version": "2.0",
  "app": "[ap2003,ap2004]",
  "EAP_ID": "0310410123456789@nai.epc.mnc410.mcc310.3gppnetwork.org"
}

Response Formats​

Accept Header​

Accept HeaderResponse Format
text/vnd.wap.connectivity-xmlXML (default)
application/jsonJSON
application/vnd.gsma.eap-relay.v1.0+jsonEAP relay JSON

XML Response​

<?xml version="1.0"?>
<wap-provisioningdoc version="1.1">
  <characteristic type="VERS">
    <parm name="version" value="2"/>
    <parm name="validity" value="86400"/>
  </characteristic>
  <characteristic type="TOKEN">
    <parm name="token" value="eyJ0eXAi..."/>
    <parm name="validity" value="86400"/>
  </characteristic>
  <characteristic type="APPLICATION">
    <parm name="AppID" value="ap2004"/>
    <characteristic type="ap2004">
      <parm name="EntitlementStatus" value="1"/>
      <parm name="AddrStatus" value="2"/>
      <parm name="TC_Status" value="2"/>
      <parm name="ProvStatus" value="1"/>
    </characteristic>
  </characteristic>
</wap-provisioningdoc>

JSON Response​

{
  "Vers": {
    "version": "2",
    "validity": "86400"
  },
  "Token": {
    "token": "eyJ0eXAi...",
    "validity": "86400"
  },
  "ap2004": {
    "EntitlementStatus": "1",
    "AddrStatus": "2",
    "TC_Status": "2",
    "ProvStatus": "1"
  }
}

EAP Challenge Response​

When EAP-AKA authentication is in progress:

{
  "eap-relay-packet": "AQEALBcBAAAn..."
}

Application IDs​

Supported Applications​

App IDServiceReference
ap2003Voice-over-Cellular (VoLTE/VoNR)TS.43 Section 4
ap2004Voice-over-WiFi (VoWiFi)TS.43 Section 3
ap2005SMS-over-IPTS.43 Section 5
ap2006ODSA CompanionTS.43 Section 6
ap2009ODSA PrimaryTS.43 Section 6
ap2010Data Plan BoostTS.43 Section 7
ap2011Server Initiated RequestsTS.43 Section 8
ap2012Direct Carrier BillingTS.43 Section 9
ap2013Private User IdentityTS.43 Section 10
ap2014Phone Number InformationTS.43 Section 11
ap2016Satellite EntitlementTS.43 Section 12

VoWiFi (ap2004) Response Fields​

FieldTypeValuesDescription
EntitlementStatusInteger0-3Service availability
AddrStatusInteger0-3E911 address verification status
TC_StatusInteger0-3Terms & Conditions status
ProvStatusInteger0-3Provisioning status
ServiceFlow_URLStringURLService flow URL
ServiceFlow_UserDataString-Data for service flow

Status Values:

ValueEntitlementStatusAddrStatus/TC_Status/ProvStatus
0DisabledNot Available
1EnabledAvailable
2IncompatibleNot Required
3ProvisioningIn Progress

VoLTE (ap2003) Response Fields​

VoLTE uses an array of entries per access technology:

FieldTypeValuesDescription
AccessTypeInteger1=LTE, 2=NRRadio access technology
HomeRoamingNWTypeInteger1-3Network scope
EntitlementStatusInteger0-1Service availability
NetworkVoiceIRATCapabilityString-Voice capability (5G only)

HomeRoamingNWType Values:

ValueMeaning
1Home and Roaming
2Home Only
3Roaming Only

Error Responses​

HTTP StatusMeaningDescription
400Bad RequestMissing required parameters
403ForbiddenAuthentication failed
406Not AcceptableUnsupported protocol version
511Network Authentication RequiredToken invalid or EAP-AKA required

Error Response Format​

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Bad Request: Missing parameters ["terminal_id"]

Custom Entitlements​

Setting Custom Entitlements​

Use the management API to set custom entitlements for specific subscribers:

POST /api/entitlements/{imsi}
Content-Type: application/json

{
  "app_id": "ap2004",
  "entitlement": {
    "entitlement_status": 0,
    "addr_status": 1,
    "tc_status": 1,
    "prov_status": 0,
    "service_flow_url": "https://activate.example.com/vowifi",
    "message_for_incompatible": "VoWiFi requires address verification"
  }
}

Retrieving Entitlements​

GET /api/entitlements/{imsi}

Returns all custom entitlements for the subscriber:

{
  "imsi": "310410123456789",
  "entitlements": {
    "ap2004": {
      "entitlement_status": 1,
      "addr_status": 2,
      "tc_status": 2,
      "prov_status": 1
    }
  }
}

Activity Logging​

All entitlement requests are logged for audit purposes.

Searching Activity​

GET /api/activity?imsi=310410123456789&from=1704067200&to=1704153600&limit=100
ParameterTypeDescription
imsiStringFilter by subscriber IMSI
terminal_idStringFilter by device terminal ID
fromIntegerStart timestamp (Unix epoch)
toIntegerEnd timestamp (Unix epoch)
limitIntegerMaximum records to return
offsetIntegerPagination offset

Activity Record​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00Z",
  "imsi": "310410123456789",
  "terminal_id": "123456789012345",
  "terminal_vendor": "Google",
  "terminal_model": "Pixel8",
  "app_ids": ["ap2003", "ap2004"],
  "client_ip": "192.168.1.100",
  "user_agent": "PRD-TS43 Goog/Pixel8 client-IMS-Entitlement/1.0 OS-Android/14.0",
  "auth_method": "TOKEN",
  "response_code": 200
}

Android Client Compatibility​

OmniSEP is tested against the Android AOSP service_entitlement library.

User-Agent Format​

Android devices use this User-Agent format:

PRD-TS43 term-<vendor>/<model> <client_ts43>/<app_version> OS-Android/<sw_version>

Example:

PRD-TS43 term-Google/Pixel8 client-IMS-Entitlement/1.0 OS-Android/14.0

Multiple App IDs​

Android sends multiple app IDs in POST requests as a bracket-enclosed string:

{
  "app": "[ap2003,ap2004]"
}

OmniSEP parses both formats:

  • "ap2003,ap2004" - Comma-separated
  • "[ap2003,ap2004]" - Bracket-enclosed (Android format)
  • ["ap2003", "ap2004"] - JSON array

Reference Specifications​

SpecificationDescription
GSMA TS.43Service Entitlement Configuration
GSMA RCC.14IMS Device Configuration Guidelines
3GPP TS 33.220Generic Bootstrapping Architecture (GBA)
3GPP TS 29.273EPS AAA Interfaces (SWm)
Last updated on