Migrating from v1 to v2 of Lock for iOS


Access TokenLock 2.0 is the latest major release of Lock iOS-OSX. This guide is provided in order to ease the transition of existing applications using Lock 1.x to the latest APIs.

What can I use Rules for?


  • iOS 9.0+
  • Xcode 8.0+
  • Swift 3.0+


Objective-C support

Lock v2 cannot be used from Objective-C, since its public API relies on Swift features and that makes them unavailable in ObjC codebases.

If you are willing to have some Swift code in your existing application, you can follow this guide on how to mix Objective-C and Swift and then use Lock v2 from the Swift files.

If that's not an option, we recommend sticking with Lock v1 or using Auth0.swift to build your own interface for user logins and signups.

Execution order

Benefits of upgrading

  • Complete Swift 3 Compatibility: The new version includes the adoption of the new API Design Guidelines.
  • Improved UI: having a professional looking login box that displays well on any device.
  • Extensive configuration: Lock provides improved configuration options to help customize the experience to your users needs.
  • Safari controller for web-based Auth: Following Google's recent ban of WebView based auth, Lock (and Auth0.swift) will always use SFSafariViewController when web auth is needed.
  • API Authorization support: Adds support for Auth0 API Authorization

Available modules

Changes from v1

Lock 2.0 has adopted to all of the new Swift 3 changes and conventions, including the new API Design Guidelines. Because of this, almost every API in Lock has been modified in some way. This guide will attempt to identify the most common usages and how they have changed, to help you get started with Lock 2.0. For yet more information on Lock 2.0, you can also see the Lock 2.0 Reference documentation.

Integration with your Application

Lock needs to be notified for some of your application state changes and some events/notifications your application receives from the OS. You can do all these things in the AppDelegate

Application finished launching

In Lock v1 you'd add the following:

In Lock v2, this is no longer required.

Application is asked to open URL

In Lock v1 you'd add the following:

In Lock v2 you need to instead use the following:

Application is asked to continue a User Activity

If you are using Lock scopespasswordless and have specified the .magicLink option to send the user a universal link then you will need to add the following to your AppDelegate.swift:


Lock by default will handle Email/Password, Enterprise & Social authentication based on your application's connections enabled in your Auth0 Dashboard under "Connections" in your application settings.

Auth0 credentials

Like in v1, in your application bundle you can add a plist file named Auth0.plist with the following format:

This will load your Auth0 credentials.

Classic mode (Database, Enterprise & Social authentication)

In v1 to show Lock from a UIViewController you'd add the following code:

In v2, to show Lock, the following code will be necessary:

So, in the onAuth callback, you'd only receive the credentials of the user when the authentication is successful.

In contrast with Lock v1, in v2, Lock will dismiss itself so there is no need to call dismissViewController(animated:, completion:) in any of the callbacks.

In the case you need to know about the errors or signup, there are the corresponding onError and onSignUp callbacks that can be employed.

The callback onSignUp is only called when the "login after signup" is disabled.

Passwordless mode (Email & SMS connections)

In v1 to show Lock Passwordless from a UIViewController you'd need to use either:


or SMS:

In V2 both email and sms now use the same method:


  • Passwordless can only be used with a single connection and will prioritize the use of email connections over SMS.
  • The audience option is not available in Passwordless.

Configuration options

If you needed to tweak Lock behaviour using its options in v1, you would use the following format:

In Lock v2 you can do it all before presenting Lock by using this format:

UI customizations

In v1 all UI customizations were performed using the A0Theme object in this format:

In Lock v2, the UI customization is done using the withStyle function:

Use Auth0.Swift Library to access user profile

Lock can no longer directly access user profile information. To do so, you will now need to use the Auth0.Swift library. Below is an example of accessing userInfo with Auth0.Swift:


By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate.

Delegation is not available through Lock. It can be implemented via a legacy method in Auth0.Swift for tenants which existed prior to June 2017.