Migrating from AWS SDK for iOS to Amplify Swift

July 17, 2025 · View on GitHub

This guide helps you migrate your iOS app from the legacy AWS SDK for iOS to the modern Amplify Swift library.

General Migration Notes

Amplify Swift is the recommended library for all new iOS/macOS/watchOS/tvOS development.
For any AWS service not yet supported by Amplify, you can use the AWS SDK for Swift or reference Swift SDK code examples.
For IoT, migrate to the AWS IoT Device SDK for Swift.
Amplify will make a best-effort attempt to preserve user auth sessions during migration, but some users may need to re-authenticate.

Choose Your Migration Path

If you have an existing Amplify Gen1 project:

Continue using Amplify Gen1 and follow the migration tables below. Your existing backend configuration and resources will work seamlessly with Amplify Swift.

If you don't have an Amplify project or are starting fresh:

We recommend using Amplify Gen2 for new projects. Gen2 provides a modern fullstack TypeScript developer experience with improved performance and simplified deployment.

Note: This guide focuses on migrating to Amplify Gen1 to maintain compatibility with existing Amplify backends. For Gen2 migration guidance, see the Gen2 documentation.

Category‑by‑category migration

Authentication

AWS Mobile SDK for iOS	Amplify Swift
SignUp	SignUp
Confirm SignUp	Confirm SignUp
Sign In	Sign In
Guest Access	Guest Access
Federated Identities	Federated Identities
Custom Auth Flow	Custom Auth Flow
Track/Remember Device	Track/Remember Device
Drop‑in UI (Deprecated `AWSMobileClient`)	Amplify UI Authenticator
Change Password	Change Password
Forgot Password	Reset Password
Tokens & Credentials	Accessing Credentials
Global SignOut	Global SignOut
Hosted UI	Sign in with Web UI

Note – Social sign‑in in Authenticator for SwiftUI is under active development; track progress in the GitHub repo.

Storage

AWS Mobile SDK for iOS	Amplify Swift
Upload File	Upload File
Download File	Download File
Progress Tracking	Supported via completion handlers & async sequences
Pause Transfers, Resume Transfers	Pause/Resume supported for downloads/uploads
Cancel Transfers	Cancel supported for downloads/uploads
Transfer with Metadata	Supported (`StorageUploadFileRequest.Options.metadata`)
Background Transfers	Not currently supported in Amplify Swift (see SDK doc)

REST API

(Replace AWSAPIGatewayClient)

AWS Mobile SDK for iOS	Amplify Swift
Invoke	Create / Fetch / Update / Delete
IAM Auth	Configure IAM
Cognito User Pools Authorization	Cognito User Pools Authorization

GraphQL API

(Replace AWSAppSyncClient)

AWS Mobile SDK for iOS	Amplify Swift
Run Queries, Run Mutations	Query Data / Mutate Data
Subscriptions	Real‑time Subscribe
Auth Modes	Configure Auth Modes

Push Notifications

Pinpoint deprecation notice – Pinpoint will be retired Oct 30 2026. Plan migrations accordingly.

AWS SDK for iOS	Amplify Swift
Setup	Setup
Push Notification Service Setup	Push Notification Service Setup
Register Device	Register Device
Record Notification Events	Record Notification Events

Analytics

Pinpoint deprecation notice – Pinpoint will be retired Oct 30 2026. Plan migrations accordingly.

AWS SDK for iOS	Amplify Swift
Manually Track Session	Automatically Track Session
Add Analytics	Add Analytics
Authentication Events	Authentication Events
Custom Events	Custom Events

AWS IoT

Amplify currently does not expose an IoT category. Use the standalone AWS IoT Device SDK for Swift, which works side‑by‑side with Amplify.

// Example: Connect & subscribe with AWS IoT Device SDK Swift
import AwsIot
...

When Amplify doesn't cover a service

For AWS services without an Amplify category (e.g., Amazon SQS, EventBridge, DynamoDB Streams) import the AWS SDK for Swift directly.
See runnable examples in the aws‑doc‑sdk‑examples/swift repository.

Tip – You can share credentials between Amplify and AWS SDK by passing Amplify.Auth.fetchAuthSession() credentials into service client configuration.

Migration checklist

Remove SDK pods / SPM packages for AWSMobileClient, AWSS3TransferUtility, etc.
Backend setup:
- Existing Amplify Gen1 project: Run amplify pull to download your configuration
- New project: Set up Amplify Gen2 or use existing AWS resources
Add Amplify Swift libraries and required plugins via SPM.
Initialize Amplify in your App's entry point.
Replace legacy calls using the tables above.
Build & test: verify
- Existing users stay signed in
- S3 uploads/downloads work
- API calls succeed
- Analytics events appear in Pinpoint

FAQ

Can I mix AWS Mobile SDK for iOS and Amplify Swift (Amplify v2) in the same app?

No. AWS Amplify explicitly does not support using the AWS Mobile SDK for iOS and Amplify Swift (Amplify v2) together in the same app. This is due to overlapping implementations, conflicting dependencies, and import issues. Attempting to use both in the same project can result in unpredictable behavior, build errors, and runtime issues.

For a successful migration, you must fully remove the AWS Mobile SDK for iOS from your project before integrating Amplify Swift (Amplify v2).

Will my users be forced to sign in again?
No. When Amplify is pointed at the same Cognito User Pool and key‑chain location, it detects cached refresh tokens and continues the session automatically.