For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

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:

  1. In Xcode, select your app target, navigate to Signing & Capabilities, click + Capability, and add Near Field Communication Tag Reading.

    Paid Apple Developer Program required

    Apple requires a paid Apple Developer Program team membership to sign apps with NFC Tag Reading. Personal/free development teams are not supported.

  2. 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>
Troubleshooting nfcNotSupported

If 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 NFCReaderUsageDescription and com.apple.developer.nfc.readersession.iso7816.select-identifiers keys are present in your Info.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:

  1. Install the AWS Command Line Interface (one-time setup).
  2. Configure AWS credentials (one-time setup).
  3. Authenticate Swift Package Manager (branching according to your project structure).
  4. Finalise Swift Package Manager configuration for Xcode.
  5. Add the package to your project.
Token expiration

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.

Obtain AWS credentials from Signicat

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
}
Restart Xcode

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​

  1. Open your project in Xcode.
  2. Select File > Add Package Dependencies... (or select your project in the Project Navigator > Package Dependencies tab > click +).
  3. In the search field at the top right, enter the package identifier:
    signicat.idproofing
  4. Press Enter.
  5. 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.
  6. Select the dependency rule (e.g., exact version or version range), select the IDProofing library 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 as Info.plist permissions 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)
}
)
)
)