Link iOS SDK
Reference for integrating with the Link iOS SDK
This guide covers the latest major version of the Link iOS SDK, which is version 2.x. iOS Link SDK versions prior to 2.2.2 (released October 2021) will no longer work with the Plaid API as of November 1, 2022. If you are using an older version of the SDK, consult the migration guide.
Overview
The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid from within your iOS app. LinkKit is a drop-in framework that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc.) without passing sensitive information to your server.
To get started with Plaid Link for iOS, clone the GitHub repository and try out the example application, which provides a reference implementation in both Swift and Objective-C. Youʼll want to sign up for free API keys through the Plaid Developer Dashboard to get started.

Initial iOS setup
Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project.
Register your redirect URI
- Sign in to the Plaid Dashboard and go to the Team Settings -> API page.
- Next to Allowed redirect URIs click Configure then Add New URI.
- Enter your redirect URI, which you must also set up as a Universal Link
for your application, for example:
https://app.example.com/plaid/
. - Click Save Changes.
These redirect URIs must be set up as Universal Links in your application. For details, see Apple's documentation on Allowing Apps and Websites to Link to Your Content.
Plaid does not support registering URLs with custom URL schemes as redirect URIs since they lack the security of Universal Links through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from iOS. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete Plaid OAuth flows, it is important that your application is opened and not any arbitrary application that has registered the same URL scheme.
Set up Universal Links
In order for Plaid to return control back to your application after a user
completes a bank's OAuth flow, you must specify a redirect URI, which will be the URI from which
Link will be re-launched to complete the OAuth flow. The redirect URI must be a
Universal Link.
An example of a typical redirect URI is: https://app.example.com/plaid
.
Universal Links consist of the following parts:
- An
applinks
entitlement for the Associated Domains capability in your app. For details, see Apple’s documentation on the Associated Domains Entitlement and the entitlements example in the LinkDemo-Swift example app. - Code in your app handling the user activity when your app is opened via Universal Links.
For details, see Apple's documentation on
Supporting Universal Links
in your app and
the
AppDelegate
example in the LinkDemo-Swift example app. The Plaid Link SDK will ignore unexpected URLs passed tocontinue(from:)
as per Apple’s recommendations, so there is no need to filter out unrelated URLs. Doing so may prevent a valid URL from being passed tocontinue(from:)
and OAuth may not continue as expected. - An
apple-app-site-association
file on your website. For details, see Apple’s documentation on Supporting Associated Domains and see our minimal example below.
There are a few requirements for apple-app-site-association
files:
- Must be a static JSON file
- Must be hosted using a
https://
scheme with a valid certificate and no redirects - Must be hosted at
https://<my-fully-qualified-domain>/.well-known/apple-app-site-association
Below is an example for https://my-app.com
(https://my-app.com/.well-known/apple-app-site-association
)
1{2 "applinks": {3 "details": [4 {5 "appIDs": [ "<My Application Identifier Prefix>.<My Bundle ID>" ],6 "components": [7 {8 "/": "/plaid/*",9 "comment": "Matches any URL path whose path starts with /plaid/"10 }11 ]12 }13 ]14 }15}
Once you have enabled Universal Links, your iOS app is now set up and ready to start integrating with the Plaid SDK.
Ensure that the corresponding entry for the configured redirect URI in the apple-app-site-association
file on your website continues to be available. If it is removed, OAuth sessions will fail until it is available again.
Installation
Plaid Link for iOS is an embeddable framework that is bundled and distributed with your application.
There are several ways to obtain the necessary files and keep them up-to-date; we
recommend using Swift Package Manager or CocoaPods.
Regardless of what you choose, submitting a new version of your application with the updated
LinkKit.xcframework
to the App Store is required.
Requirements
LinkKit iOS version | Xcode toolchain minimum support | Supported iOS versions |
---|---|---|
LinkKit 3.0.0 | Xcode 13 | iOS 11 or greater |
LinkKit 1.0.0 - 2.5.1 | Xcode 11.5 | iOS 11 or greater |
Swift Package Manager
- To integrate LinkKit using Swift Package Manager, Swift version >= 5.3 is required.
- In your Xcode project from the Project Navigator (Xcode ❯ View ❯ Navigators ❯ Project ⌘ 1) select your project, activate the Package Dependencies tab and click on the plus symbol ➕ to open the Add Package popup window:
- Enter the LinkKit package URL
https://github.com/plaid/plaid-link-ios
into the search bar in the top right corner of the Add Package popup window. - Select the
plaid-link-ios
package. - Choose your Dependency Rule (we recommend Up to Next Major Version).
- Select the project to which you would like to add LinkKit, then click Add Package:
- Select the
LinkKit
package product and click Add Package: - Verify that the LinkKit Swift package was properly added as a package dependency to your project:
- Select your application target and ensure that the LinkKit library is embedded into your application:
Camera Support (Identity Verification only)
When using the Identity Verification product, the Link SDK may use the camera if a user
needs to take a picture of identity documentation. To support this workflow, add a NSCameraUsageDescription
entry to your application's plist
with an informative string. This allows iOS to prompt the user for camera access. iOS will crash your application if
this string is not provided.
Upgrading
A new version of LinkKit.xcframework
will be released around the 15th of every month. We recommend you keep up to
date to provide the best Plaid Link experience in your application.
For details on each release see the GitHub releases and version release notes. To upgrade Plaid Link iOS from 1.x to 2.x, refer to the iOS 1.x to 2.x migration guide.
Opening Link
Before you can open Link, you need to first create a link_token
. A link_token
can be configured for
different Link flows and is used to control much of Link’s behavior. To learn how to create a new
link_token
, see the API Reference entry for /link/token/create
.
For iOS the /link/token/create
call must include the redirect_uri
parameter and it must
match the redirect URI you have configured with Plaid
(see Register your redirect URI above).
Create a Configuration
Starting the Plaid Link for iOS experience begins with creating a link_token
. Once the link_token
is passed to your app, create an instance of LinkTokenConfiguration
, then create a Handler
using Plaid.create()
passing the previously created LinkTokenConfiguration
, and call open()
on the handler passing your preferred presentation method. Note that each time you open Link, you will need to get a new link_token
from your server and create a new LinkTokenConfiguration
with it.
token String Specify a link_token to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a link_token can be configured to launch Link in update mode for Items with expired credentials, or the Payment Initiation flow. See the /link/token/create endpoint for more details. |
1var linkConfiguration = LinkTokenConfiguration(2 token: "<#LINK_TOKEN_FROM_SERVER#>",3 onSuccess: { linkSuccess in4 // Send the linkSuccess.publicToken to your app server.5 }6)
Create a Handler
A Handler
is a one-time use object used to open a Link session. The Handler
must
be retained for the duration of the Plaid SDK flow. It will also be needed to respond to OAuth Universal Link
redirects. For more details, see the OAuth guide.
1let result = Plaid.create(configuration)2switch result {3 case .failure(let error):4 logger.error("Unable to create Plaid handler due to: \(error)")5 case .success(let handler):6 self.handler = handler7}
Open Link
Finally, open Link by calling open
on the Handler
object.
This will usually be done in a button’s target action.
1let method: PresentationMethod = .viewController(self)2handler.open(presentUsing: method)
Handling redirect URIs
When your app is opened via an Universal Link, it must check whether the opened URL is the redirect URI registered with Plaid and pass the URL to LinkKit to complete the account linking flow.
1if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let redirectUri = userActivity.webpageURL {2 // NOTE: Your handler must be accessible from your application delegate or scene delegate.3 self.handler.continue(from: redirectUri)4}
onSuccess
The closure is called when a user successfully links an Item. It should take a single LinkSuccess
argument, containing the publicToken
String and a metadata
of type SuccessMetadata
.
linkSuccess LinkSuccess Contains the publicToken and metadata for this successful flow.
|
1onSuccess: { linkSuccess in2 // Send the linkSuccess.publicToken to your app server.3}
onExit
This optional closure is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It should take a single LinkExit
argument, containing an optional error
and a metadata
of type ExitMetadata
.
linkExit LinkExit Contains the optional error and metadata for when the flow was exited.
|
1linkConfiguration.onExit = { linkExit in2 // Optionally handle linkExit data according to your application's needs3}
onEvent
This optional closure is called when certain events in the Plaid Link flow have occurred, for example, when the user selected an institution. This enables your application to gain further insight into what is going on as the user goes through the Plaid Link flow.
The following onEvent
callbacks are stable, which means that they will not be deprecated or changed: open
, exit
, handoff
, selectInstitution
, error
, bankIncomeInsightsCompleted
. The remaining callback events are informational and subject to change.
linkEvent LinkEvent Contains the eventName and metadata for the Link event.
|
1linkConfiguration.onEvent = { linkEvent in2 // Optionally handle linkEvent data according to your application's needs3}
Next steps
Once you've gotten Link working, see Link best practices for recommendations on further improving the Link flow.