Installation

Swift Package Manager

In Xcode

1. Open your project in Xcode
2. Go to File > Add Package Dependencies...
3. Enter the repository URL provided to you
4. Select a version rule (e.g. Up to Next Major) and click Add Package
5. Add the modules you need to your targets:

Target	Add these products
Main App	KapeCore, KapeAuth, KapeVPN
Network Extension	KapeVPN

In Package.swift

dependencies: [
    .package(url: "<repository-url>", from: "1.0.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "KapeCore", package: "KapePlatformSDK"),
            .product(name: "KapeAuth", package: "KapePlatformSDK"),
            .product(name: "KapeVPN", package: "KapePlatformSDK"),
        ]
    ),
]

info

The Low Level SDK (KapeClientSDK) is included as a transitive dependency. You do not need to add it separately.

Configuration File

Create a KapeSDK.plist file and add it to both your app target and Network Extension target:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
        "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>BrandId</key>
        <string>your-brand-id</string>
        <key>Environment</key>
        <string>Production</string>
        <key>MaxLogLevel</key>
        <string>Info</string>
        <key>ClientId</key>
        <string>your-oidc-client-id</string>
        <key>IssuerURL</key>
        <string>https://auth.example.com/realms/your-tenant</string>
        <key>RedirectURL</key>
        <string>your-app-scheme://callback</string>
        <key>AppGroupIdentifier</key>
        <string>group.com.your.app</string>
        <key>KeychainService</key>
        <string>com.your.app.sdk-storage</string>
        <key>ServerAddress</key>
        <string>vpn.example.com</string>
        <key>PacketTunnelBundleIdentifier</key>
        <string>com.your.app.PacketTunnel</string>
        <key>YAMLConfigName</key>
        <string>your_config</string>
        <key>License</key>
        <string>your-license-key</string>
    </dict>
</plist>

Key	Required	Description
BrandId	Yes	Brand identifier provided to you
Environment	Yes	Production or Staging
MaxLogLevel	No	Off, Error, Warn, Info, Debug, Trace (default: Info)
ClientId	Yes	OIDC client ID
IssuerURL	Yes	OIDC issuer URL for discovery
RedirectURL	Yes	OIDC redirect URI (must match your URL scheme)
AppGroupIdentifier	Yes	Shared App Group for app + extension IPC
KeychainService	Yes	Keychain service name for token storage
ServerAddress	No	Display address in iOS VPN settings
PacketTunnelBundleIdentifier	Yes	Bundle ID of your Network Extension
YAMLConfigName	Yes	Name of the YAML config file (without .yaml)
License	Yes	SDK license key provided to you

warning

The same KapeSDK.plist must be included in both your app target and Network Extension target. The extension reads it to initialize the SDK with identical settings.

YAML Configuration

Place the YAML configuration file provided to you in your app bundle. The file name must match the YAMLConfigName value in KapeSDK.plist (e.g. your_config.yaml).

Entitlements

Both your app and Network Extension require these entitlements:

<key>com.apple.developer.networking.networkextension</key>
<array>
<string>packet-tunnel-provider</string>
</array>
<key>com.apple.security.application-groups</key>
<array>
<string>group.com.your.app</string>
</array>

Network Extension Target

Create a Network Extension target (Packet Tunnel Provider) in your Xcode project with a minimal subclass:

import KapeVPN

class PacketTunnelProvider: KapePacketTunnelProvider {}

The base class handles everything: SDK initialization, endpoint discovery, WireGuard tunnel management, and connection lifecycle.