eSIM Management¶

This section covers the management of embedded SIMs (eSIMs) through the TelcoAPI platform, following GSMA specifications.

Overview¶

eSIM technology enables remote SIM provisioning and management without physical SIM cards. The TelcoAPI platform provides comprehensive support for eSIM management following GSMA SGP.22 and SGP.21 specifications.

Key Components¶

Subscription Manager Data Preparation (SM-DP+)¶

The SM-DP+ is responsible for: - Securely preparing subscription profiles - Managing the lifecycle of profiles - Protecting operator credentials - Facilitating profile downloads

Local Profile Assistant (LPA)¶

The LPA resides on the device and handles: - Profile discovery and download - Profile installation and enablement - Local profile management - User consent management

Data Model¶

interface ESimProfile {
  iccid: string;                // Integrated Circuit Card Identifier
  eid: string;                  // eUICC Identifier
  profileState: ProfileState;    // Current state of the profile
  activationCode: string;       // Activation code for profile download
  profileType: string;          // Type of profile (e.g., operational, test)
  mno: string;                  // Mobile Network Operator identifier
  createdAt: Date;             // Profile creation timestamp
  expiresAt?: Date;            // Profile expiration date
  metadata: ProfileMetadata;    // Additional profile metadata
}

interface ProfileMetadata {
  name: string;                // Profile name
  description: string;         // Profile description
  icon?: string;              // Profile icon URL
  policies: ProfilePolicy[];   // Profile policies
  features: string[];         // Supported features
}

enum ProfileState {
  CREATED = 'CREATED',
  DOWNLOADED = 'DOWNLOADED',
  INSTALLED = 'INSTALLED',
  ENABLED = 'ENABLED',
  DISABLED = 'DISABLED',
  DELETED = 'DELETED'
}

API Operations¶

Profile Management¶

class ESimProfileManager {
  async createProfile(profileData: ESimProfile): Promise<string> {
    // Implementation for creating a new eSIM profile
  }

  async generateActivationCode(iccid: string): Promise<string> {
    // Implementation for generating activation code
  }

  async downloadProfile(activationCode: string): Promise<void> {
    // Implementation for profile download
  }

  async enableProfile(iccid: string): Promise<void> {
    // Implementation for enabling a profile
  }

  async disableProfile(iccid: string): Promise<void> {
    // Implementation for disabling a profile
  }

  async deleteProfile(iccid: string): Promise<void> {
    // Implementation for deleting a profile
  }
}

Device Management¶

class ESimDeviceManager {
  async registerDevice(eid: string, deviceInfo: DeviceInfo): Promise<void> {
    // Implementation for registering an eSIM-capable device
  }

  async checkCompatibility(eid: string): Promise<CompatibilityResult> {
    // Implementation for checking device compatibility
  }

  async getAvailableProfiles(eid: string): Promise<ESimProfile[]> {
    // Implementation for retrieving available profiles
  }
}

Error Handling¶

enum ESimError {
  INVALID_ACTIVATION_CODE = 'INVALID_ACTIVATION_CODE',
  PROFILE_DOWNLOAD_FAILED = 'PROFILE_DOWNLOAD_FAILED',
  DEVICE_NOT_COMPATIBLE = 'DEVICE_NOT_COMPATIBLE',
  PROFILE_NOT_FOUND = 'PROFILE_NOT_FOUND',
  OPERATION_NOT_PERMITTED = 'OPERATION_NOT_PERMITTED',
  NETWORK_ERROR = 'NETWORK_ERROR'
}

interface ESimErrorResponse {
  error: ESimError;
  message: string;
  details?: Record<string, any>;
  timestamp: Date;
}

Implementation Example¶

Here's a complete example of implementing an eSIM profile manager:

class ESimProfileManagerImpl implements ESimProfileManager {
  private smdp: SmDpPlus;
  private db: Database;
  private logger: Logger;

  constructor(smdp: SmDpPlus, db: Database, logger: Logger) {
    this.smdp = smdp;
    this.db = db;
    this.logger = logger;
  }

  async createProfile(profileData: ESimProfile): Promise<string> {
    try {
      // Validate profile data
      this.validateProfileData(profileData);

      // Generate profile package
      const profilePackage = await this.smdp.prepareProfile({
        iccid: profileData.iccid,
        mno: profileData.mno,
        profileType: profileData.profileType,
        metadata: profileData.metadata
      });

      // Store profile data
      await this.db.insertProfile({
        ...profileData,
        profileState: ProfileState.CREATED,
        createdAt: new Date()
      });

      // Generate activation code
      const activationCode = await this.generateActivationCode(profileData.iccid);

      this.logger.info(`Profile created successfully for ICCID: ${profileData.iccid}`);

      return activationCode;
    } catch (error) {
      this.logger.error(`Failed to create profile: ${error.message}`);
      throw new ESimError(error.code, error.message);
    }
  }

  async downloadProfile(activationCode: string): Promise<void> {
    try {
      // Decode activation code
      const profileInfo = this.decodeActivationCode(activationCode);

      // Verify profile exists
      const profile = await this.db.findProfileByIccid(profileInfo.iccid);
      if (!profile) {
        throw new ESimError(ESimError.PROFILE_NOT_FOUND);
      }

      // Initiate download through SM-DP+
      await this.smdp.downloadProfile(profileInfo);

      // Update profile state
      await this.db.updateProfileState(
        profileInfo.iccid,
        ProfileState.DOWNLOADED
      );

      this.logger.info(`Profile downloaded successfully for ICCID: ${profileInfo.iccid}`);
    } catch (error) {
      this.logger.error(`Profile download failed: ${error.message}`);
      throw new ESimError(ESimError.PROFILE_DOWNLOAD_FAILED, error.message);
    }
  }

  private validateProfileData(profileData: ESimProfile): void {
    // Implement validation logic
  }

  private decodeActivationCode(activationCode: string): ProfileInfo {
    // Implement activation code decoding
  }
}

API Endpoints¶

The following REST endpoints are available for eSIM management:

// Profile management endpoints
POST /api/v1/esim/profiles
GET /api/v1/esim/profiles/{iccid}
POST /api/v1/esim/profiles/{iccid}/download
POST /api/v1/esim/profiles/{iccid}/enable
POST /api/v1/esim/profiles/{iccid}/disable
DELETE /api/v1/esim/profiles/{iccid}

// Device management endpoints
POST /api/v1/esim/devices
GET /api/v1/esim/devices/{eid}
GET /api/v1/esim/devices/{eid}/profiles
POST /api/v1/esim/devices/{eid}/check-compatibility

// Activation code management
POST /api/v1/esim/activation-codes
GET /api/v1/esim/activation-codes/{code}

API Reference¶

Profile Management API¶

Create Profile¶

Creates a new eSIM profile in the system.

POST /api/v1/esim/profiles

// Request body
{
  "iccid": string,          // Required: ICCID for the profile
  "eid": string,           // Required: eUICC identifier
  "profileType": string,   // Required: "OPERATIONAL" | "PROVISIONING" | "TESTING"
  "mno": string,          // Required: Mobile Network Operator identifier
  "metadata": {
    "name": string,       // Required: Profile name
    "description": string, // Required: Profile description
    "icon"?: string,      // Optional: Profile icon URL
    "policies": [         // Required: Array of profile policies
      {
        "type": string,   // Policy type
        "value": any      // Policy value
      }
    ],
    "features": string[]  // Required: Supported features
  },
  "expiresAt"?: string   // Optional: ISO 8601 date string
}

// Response 200 OK
{
  "profileId": string,
  "activationCode": string,
  "createdAt": string,
  "status": "CREATED"
}

// Error Response 400 Bad Request
{
  "error": "INVALID_REQUEST",
  "message": "Invalid profile data",
  "details": {
    "field": "iccid",
    "reason": "Invalid format"
  }
}

Generate Activation Code¶

Generates a new activation code for an existing profile.

POST /api/v1/esim/profiles/{iccid}/activation-code

// Response 200 OK
{
  "activationCode": string,
  "expiresAt": string,    // ISO 8601 date string
  "remainingUses": number
}

Download Profile¶

Initiates profile download using an activation code.

POST /api/v1/esim/profiles/download

// Request body
{
  "activationCode": string,  // Required: Activation code
  "eid": string,            // Required: Device eUICC identifier
  "confirmationRequired": boolean  // Optional: Whether user confirmation is needed
}

// Response 202 Accepted
{
  "operationId": string,
  "status": "IN_PROGRESS",
  "estimatedTime": number  // Estimated time in seconds
}

Enable Profile¶

Enables a downloaded profile on a device.

POST /api/v1/esim/profiles/{iccid}/enable

// Response 200 OK
{
  "status": "ENABLED",
  "timestamp": string,
  "operationId": string
}

Device Management API¶

Register Device¶

Registers a new eSIM-capable device.

POST /api/v1/esim/devices

// Request body
{
  "eid": string,           // Required: eUICC identifier
  "deviceInfo": {
    "manufacturer": string,
    "model": string,
    "osVersion": string,
    "lpaVersion": string,  // Local Profile Assistant version
    "capabilities": string[]
  }
}

// Response 201 Created
{
  "deviceId": string,
  "registrationDate": string,
  "status": "REGISTERED"
}

Check Device Compatibility¶

Checks if a device is compatible with specific profile types.

GET /api/v1/esim/devices/{eid}/compatibility?profileType={profileType}

// Response 200 OK
{
  "compatible": boolean,
  "reasons": string[],
  "supportedFeatures": string[],
  "restrictions": {
    "maxProfiles": number,
    "minOsVersion": string
  }
}

Batch Operations¶

Batch Profile Creation¶

Creates multiple profiles in a single request.

POST /api/v1/esim/profiles/batch

// Request body
{
  "profiles": [
    {
      // Profile data as per single profile creation
    }
  ],
  "options": {
    "failFast": boolean,
    "parallel": boolean
  }
}

// Response 200 OK
{
  "results": [
    {
      "iccid": string,
      "success": boolean,
      "activationCode"?: string,
      "error"?: {
        "code": string,
        "message": string
      }
    }
  ],
  "summary": {
    "total": number,
    "successful": number,
    "failed": number
  }
}

Webhook Notifications¶

Configure webhooks to receive real-time updates about profile and device events.

POST /api/v1/esim/webhooks

// Request body
{
  "url": string,           // Required: Webhook URL
  "events": string[],      // Required: Array of event types to subscribe to
  "secret": string,        // Required: Webhook secret for signature verification
  "description"?: string   // Optional: Webhook description
}

// Example event payload
{
  "eventType": "PROFILE_DOWNLOADED",
  "timestamp": string,
  "data": {
    "iccid": string,
    "eid": string,
    "status": string
  },
  "signature": string      // HMAC signature of the payload
}

Rate Limits¶

Endpoint	Rate Limit
Profile Creation	100 requests/minute
Profile Download	50 requests/minute
Device Registration	30 requests/minute
Activation Code Generation	100 requests/minute

Error Codes¶

Code	Description
`INVALID_ACTIVATION_CODE`	The provided activation code is invalid or expired
`PROFILE_DOWNLOAD_FAILED`	Failed to download profile to device
`DEVICE_NOT_COMPATIBLE`	Device is not compatible with the profile
`PROFILE_NOT_FOUND`	The requested profile does not exist
`OPERATION_NOT_PERMITTED`	The requested operation is not allowed
`NETWORK_ERROR`	Network communication error with SM-DP+
`RATE_LIMIT_EXCEEDED`	API rate limit has been exceeded
`INVALID_EID`	The provided eUICC identifier is invalid
`PROFILE_LIMIT_REACHED`	Device has reached maximum number of profiles
`AUTHENTICATION_FAILED`	Failed to authenticate with SM-DP+

Security Considerations¶

Profile Protection
Implement end-to-end encryption for profile data
Use secure elements for credential storage
Implement mutual authentication
Access Control
Implement role-based access control
Enforce principle of least privilege
Maintain audit logs
Communication Security
Use TLS 1.3 for all communications
Implement certificate pinning
Regular security assessments
Compliance
Follow GSMA SGP.22 security requirements
Implement privacy controls
Regular compliance audits

Best Practices¶

Profile Management
Implement profile lifecycle hooks
Use atomic transactions for state changes
Implement retry mechanisms for failed operations
Error Handling
Implement comprehensive error logging
Use appropriate error codes
Provide detailed error messages
Performance
Implement caching for frequently accessed data
Use connection pooling
Optimize database queries
Monitoring
Track profile download success rates
Monitor SM-DP+ performance
Alert on security events

Monitoring Metrics¶

Key metrics to monitor:

Profile download success rate
Profile activation success rate
SM-DP+ response times
Device compatibility check results
Error rates by type
Profile state transition times
API endpoint performance