iOS
This section describes how to set up the Verify iOS SDK for iOS use.
System requirements
- iOS version: iOS 15.1 or later.
- Development tools: Xcode 16 or later with Swift Package Manager support, and the AWS CLI.
The SDK supports both SwiftUI and UIKit host applications, allowing you to choose the entry point that fits your app architecture (both options are described in 3. Start a validation).
1. Add app capabilities and permissions
Before launching identity proofing flows, your iOS application must declare the necessary privacy descriptions and entitlements in its Info.plist and Xcode project settings.
Info.plist privacy permissions
Add the following keys to your application's Info.plist:
NFC tag reading capability and ISO 7816 identifiers
If your verification flows include passport or ID card chip reading through NFC:
-
In Xcode, select your app target, navigate to Signing & Capabilities, click + Capability, and add Near Field Communication Tag Reading.
Paid Apple Developer Program requiredApple requires a paid Apple Developer Program team membership to sign apps with NFC Tag Reading. Personal/free development teams are not supported.
-
In your
Info.plist, declare the ISO 7816 Application Identifier (AID) used by standard electronic travel documents (ICAO Doc 9303):<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key><array><string>A0000002471001</string></array>
nfcNotSupportedIf the SDK returns a providerError with code nfcNotSupported on a physical device with NFC hardware, verify that:
- The Near Field Communication Tag Reading entitlement is present in your entitlements file and provisioned by your Apple Developer profile.
- The
NFCReaderUsageDescriptionandcom.apple.developer.nfc.readersession.iso7816.select-identifierskeys are present in yourInfo.plist.
2. Install SDK
The Verify iOS SDK is distributed as a private Swift package through AWS CodeArtifact and consumed using Apple's Swift Package Manager (SPM).
Overview of the installation steps
Integrating the private Swift package involves the following steps:
- Install the AWS Command Line Interface (one-time setup).
- Configure AWS credentials (one-time setup).
- Authenticate Swift Package Manager (branching according to your project structure).
- Finalise Swift Package Manager configuration for Xcode.
- Add the package to your project.
CodeArtifact authentication tokens are valid for 12 hours. Once expired, SPM dependency resolution and builds will fail with authentication errors until you re-authenticate.
Install the AWS Command Line Interface
Developer workstations and CI/CD environments require the AWS CLI. On macOS, you can install it through Homebrew:
brew install awscli
For other installation methods, see the AWS CLI installation guide.
Configure AWS credentials
Before you can authenticate the Swift Package Manager and download the private signicat.idproofing package from AWS CodeArtifact, you must configure the AWS CLI on your machine.
To configure the AWS CLI, you need the following credentials:
- AWS Access Key ID
- AWS Secret Access Key
To obtain these AWS credentials, contact the Signicat onboarding team at onboarding@signicat.com.
Configure your AWS CLI with these credentials (this is a one-time setup per machine):
aws configure
When prompted, provide:
- AWS Access Key ID: Provided by Signicat.
- AWS Secret Access Key: Provided by Signicat.
- Default region name:
eu-west-1 - Default output format:
json
The AWS CLI saves this information in ~/.aws/config and ~/.aws/credentials.
Authenticate Swift Package Manager
The AWS CLI uses the aws codeartifact login --tool swift command to retrieve a temporary authorisation token, store it securely in the macOS Keychain, and configure SPM to use the Signicat package registry.
Because the AWS CLI relies on Swift Package Manager's local registry commands, it expects a Package.swift manifest in the working directory. Select the path that matches your project setup, either:
- Option A: Standard Xcode application project (no
Package.swift) - Option B: Swift package / modular project (with
Package.swift)
Option A: Standard Xcode application project
Most iOS applications manage their dependencies through Xcode's project settings (.xcodeproj / .xcworkspace) rather than a root Package.swift. Running the login command directly inside your iOS app folder will fail with:
aws: [ERROR]: Command '['swift', 'package-registry', 'set', ...]' returned non-zero exit status 1. Stderr from command:
Error: Could not find Package.swift in this directory or any of its parent directories.
To authenticate cleanly without cluttering your application repository:
# 1. Create and navigate to a dedicated temporary Swift package setup directory
mkdir -p ~/idproofing-spm-setup
cd ~/idproofing-spm-setup
swift package init --type library
# 2. Authenticate SPM against the Signicat CodeArtifact repository
aws codeartifact login \
--tool swift \
--domain signicat \
--domain-owner 101014119721 \
--repository idproofing \
--namespace signicat \
--region eu-west-1
Once completed, proceed to Finalise Swift Package Manager configuration for Xcode.
Option B: Swift package / modular project
If your project is structured as a Swift Package or already contains a Package.swift file at the root:
Run the following command from the root of a Swift package containing a Package.swift file:
cd <path-to-package-root>
aws codeartifact login \
--tool swift \
--domain signicat \
--domain-owner 101014119721 \
--repository idproofing \
--namespace signicat \
--region eu-west-1
Finalise Swift Package Manager configuration for Xcode
For Xcode's dependency manager to locate and resolve the private package, the signicat registry entry must be registered in the user's global SPM configuration file: ~/.swiftpm/configuration/registries.json.
Ensure that ~/.swiftpm/configuration/registries.json contains the signicat registry under the registries dictionary alongside its authentication entry:
{
"authentication": {
"signicat-101014119721.d.codeartifact.eu-west-1.amazonaws.com": {
"loginAPIPath": "/swift/idproofing/login",
"type": "token"
}
},
"registries": {
"signicat": {
"supportsAvailability": false,
"url": "https://signicat-101014119721.d.codeartifact.eu-west-1.amazonaws.com/swift/idproofing/"
}
},
"version": 1
}
If Xcode was open while configuring the registry or authenticating, restart Xcode before attempting to add or resolve dependencies.
Add the package to your app
Through Xcode UI (recommended for iOS apps)
- Open your project in Xcode.
- Select File > Add Package Dependencies... (or select your project in the Project Navigator > Package Dependencies tab > click +).
- In the search field at the top right, enter the package identifier:
signicat.idproofing
- Press Enter.
- When Xcode queries the registry for the first time, macOS will display a Keychain prompt asking for permission to access the stored credentials. Click Always Allow so Xcode can resolve and update packages seamlessly without repeatedly interrupting you.
- Select the dependency rule (e.g., exact version or version range), select the
IDProofinglibrary product, and add it to your application target.
Through Package.swift
If managing dependencies directly in Package.swift, declare the package dependency and add IDProofing to your target dependencies:
// swift-tools-version: 5.9
import PackageDescription
let package = Package(
name: "MyApp",
dependencies: [
.package(id: "signicat.idproofing", from: "<VERSION>")
],
targets: [
.target(
name: "MyApp",
dependencies: [
.product(name: "IDProofing", package: "signicat.idproofing")
]
)
]
)
Token renewal
CodeArtifact tokens expire every 12 hours. When a token expires, package resolution and builds will fail with a 401 Unauthorized or permission error.
To refresh your credentials, re-run the login command:
# If using Option A (Xcode application project):
cd ~/idproofing-spm-setup && aws codeartifact login --tool swift --domain signicat --domain-owner 101014119721 --repository idproofing --namespace signicat --region eu-west-1
# If using Option B (Swift Package with Package.swift):
cd <path-to-package-root> && aws codeartifact login --tool swift --domain signicat --domain-owner 101014119721 --repository idproofing --namespace signicat --region eu-west-1
Troubleshooting
If you encounter issues while installing the SDK, see the table below for solutions to common issues:
3. Start a validation
All mobile SDKs start from the same backend-created session values:
sessionId: The backend-created session identifier.sdkToken: The session-scoped SDK token.- API base URL: The Verify API base URL for your Signicat environment.
- Language: Optional language preference for the SDK shell and supported provider steps. For supported languages and fallback language, see the SDK introduction.
The iOS SDK entry point is IDProofing.validate(...).
The app starts validation with InputParams, which contains:
sessionID: The backend-created session identifier.sdkToken: The session-scoped SDK token.config.baseURL: The Verify API base URL. Use the base URL for your Signicat environment.config.language: Optional language preference for the SDK shell and supported provider steps.config.observability: Optional callback for SDK diagnostic breadcrumbs.
UIKit with async/await
import IDProofing
import UIKit
let input = IDProofing.InputParams(
sessionID: UUID(uuidString: "<SESSION_ID>")!,
sdkToken: "<SDK_TOKEN>",
config: .init(
baseURL: URL(string: "https://<SIGNICAT_API_BASE_URL>")!,
language: "en"
)
)
try await IDProofing.validate(
using: input,
from: viewController
)
UIKit with a completion handler
import IDProofing
import UIKit
let input = IDProofing.InputParams(
sessionID: UUID(uuidString: "<SESSION_ID>")!,
sdkToken: "<SDK_TOKEN>",
config: .init(language: "en")
)
IDProofing.validate(
using: input,
from: viewController
) { result in
switch result {
case .success:
print("SDK flow completed")
case let .failure(error):
print(error.diagnostics)
}
}
SwiftUI
import IDProofing
import SwiftUI
struct ValidationScreen: View {
let inputParams = IDProofing.InputParams(
sessionID: UUID(uuidString: "<SESSION_ID>")!,
sdkToken: "<SDK_TOKEN>",
config: .init(language: "en")
)
var body: some View {
IDProofing.validate(using: inputParams) { result in
switch result {
case .success:
print("SDK flow completed")
case let .failure(error):
print(error.diagnostics)
}
}
}
}
Hosted shell
The SDK owns the native presentation shell while validation is running. The shell keeps the end-user inside one Signicat-managed journey until the local SDK flow completes or fails.
For UIKit integrations, the iOS SDK presents its own full-screen navigation controller from the supplied presenter. For SwiftUI integrations, the SDK embeds the same native shell inside the returned SwiftUI view.
Keep the SDK presentation alive until the flow completes or fails. Do not dismiss it between provider steps.
Error handling
The iOS SDK reports all execution failures as strongly typed IDProofingError instances.
Error categories
The error categories are:
sdkError(...): The SDK could not set up or continue the flow.providerError(...): A downstream provider reported a failure.canceled(step:): The user cancelled while a backend-defined step was running.
For example:
public enum IDProofingError: Error, Sendable, Equatable {
/// The SDK could not set up or continue the validation flow.
case sdkError(SDKError)
/// A downstream provider reported a failure.
case providerError(ProviderError)
/// The validation was canceled by the user while running the given backend step.
case canceled(step: String)
}
See more details below about SDK and provider errors.
sdkError
Contains the stable SDK error code and a human-readable message:
.alreadyInProgress("already_in_progress"): A validation flow was started while another one is still active..setupFailed("setup_failed"): The SDK could not prepare a valid local flow from backend data or required host app prerequisites (such asInfo.plistpermissions or NFC capabilities) are missing..backendFailed("backend_failed"): The SDK could not communicate with the backend, or the backend returned an error response..internalError("internal_error"): The SDK reached an unexpected internal state or received an unexpected response from the backend.
providerError
Contains downstream provider failure details:
provider: The provider that reported the failure (.videoID,.readID, or.externalWebView).step: The backend step being executed when the provider failed.code: The provider-owned error code (e.g.nfcNotSupported,Permission.Denied).message: A human-readable diagnostic message from the provider.
Diagnostic dictionary
Every error exposes a diagnostics: [String: String] dictionary containing safe, non-sensitive technical metadata that you can use for logging sinks, crash breadcrumbs, or attach to support tickets:
do {
try await IDProofing.validate(using: input, from: viewController)
} catch let error as IDProofingError {
logger.error("ID Proofing failed: \(error.diagnostics)")
}
Observability
The iOS SDK can emit optional diagnostic breadcrumbs through ObservabilityConfiguration. Use this only for logging or telemetry, and do not build product logic from breadcrumb content.
let input = IDProofing.InputParams(
sessionID: UUID(uuidString: "<SESSION_ID>")!,
sdkToken: "<SDK_TOKEN>",
config: .init(
observability: .init(
onBreadcrumb: { message in
print(message)
}
)
)
)