Clever Developer Docs

Instant Login - Native iOS Apps

Upcoming changes to SSO for iOS

We are working on a new set of best practices for integrating Clever SSO with native iOS applications. If you've already started building against the flow before, you can get certified, but if you haven't started building yet, please hold off until the new flow is available.

For more information about the new integration, or any questions about the transition, please email us at

If you have a native iOS application, you can use our SDK (CocoaPods, Github) to log users in to your application through Clever Instant Login.

iOS 11 is only supported on SDK version 1.0.0 and above.

If you’d prefer to build your integration from scratch, we've outlined the necessary steps below.

Enabling Instant Login for native iOS applications

Regardless of whether you’re using our SDK, or building your integration from scratch, you’ll need to enable iOS logins in Clever.

To get started, go to your Application Settings page and enable the iOS platform for your application:

Once you’ve enabled the iOS platform, you’ll find a new custom Redirect URL and Client ID on the Application Settings page.

The credentials above are no longer valid. You'll need to enable the iOS platform in your application to get valid credentials. If you don't see the option to enable the iOS platform, email us at

Configuration within your native iOS app

Register the custom redirect URL

Once you have the custom redirect URL, add it to your application as a custom URL scheme. If you are not sure how to do so, you can read this tutorial for help.

Finally, add com.clever to your LSApplicationQueriesSchemes in your Info.plist, so you can redirect directly to the Clever app. More information on LSApplicationQueriesSchemes can be found here.

The Instant Login flow and how to support it

Below, we’ve outlined the steps you need to take in order to support Instant Login into your native iOS app. These are also implemented in our SDK, which you can use to simplify development.

Step 1 - Prepare to initiate the login flow

When users click on your application's icon, they will be redirected to the custom URL specified in your iOS platform application settings. You should write code to handle requests at this path and initiate the login flow.

Step 2 - Set the state parameter

Next, you’ll need to create and store a random state parameter for each login. You’ll send this value to Clever and it will be returned back to you so that you can verify that it matches the original value.

See Keeping Instant Login Secure for more information on the state parameter.

Step 3 - Initiating a login

To kick off a login, redirect the user to Clever. If you're on iOS 11, you should check to see if our app is installed and, if so, initiate a login in the Clever application. For details on how to implement this, see our SDK

If the Clever application is not installed, or if the device is not using iOS 11, you should initiate a login in a web browser. Here’s the format:<your iOS platform client id>&redirect_uri=<your iOS custom redirect url>&state=<the state value you prepared in step 2>

If your app is running on iOS 11, you should open this URL using Safari.

If your app is running on iOS 9.0+, you should open this URL using SFSafariWebViewController. Otherwise, you can use UIWebView.

As of May 8, 2016, users can no longer log in to Google within UIWebView. if their device is running iOS 9.0+

Step 4 - Requesting a token

Clever will then redirect the user back to your custom URL with a code and the state parameter as provided, exactly as we do on the web.

Unlike the regular flow for browser-based logins, you do not use a client secret to for the authorization header. Instead, you should use the client ID for the iOS platform and a blank client secret, like so:

http basic_auth_header = “Authorization: Basic “ + Base64.encode(ios_client_id + “:”)

Step 5: Acquiring the token

The response from the bearer token call will yield an access token, which your app can use to access information in Clever's API. You can also use this access token to associate your server-side session with a Clever user.