AI agents: the complete RevenueCat documentation index is available at llms.txt. A Markdown version of this page is available at this URL.

Add authentication to your mobile app

Turn on authentication in the RevenueCat iOS or Android SDK and send the ID token from your identity provider after each sign-in

Ask Rico

Copied as markdown!

This article shows you how to add authentication to your iOS or Android app. You'll turn on authentication in the RevenueCat SDK, listen for authentication events, and send the ID token from your identity provider to RevenueCat after each sign-in. By the end, RevenueCat will identify each Customer from a verified ID token, and your app will hold a RevenueCat access token for that Customer.

📘Private beta

Authentication is in private beta, and its API can change before the general release. Tell us about your use case to get early access, and talk to your RevenueCat contact before you use it in a production app.

Prerequisites

• An authentication method in your RevenueCat project for the identity provider that your app uses
• The RevenueCat iOS SDK version 5.88.0 or later, installed in your app, or the RevenueCat Android SDK version 10.29.0 or later, installed in your app
• Sign-in with your identity provider working in your app, so that your app can get an ID token
• Read Authentication for how the identity provider, the method, and the access token fit together

1. Turn on authentication in the SDK

On iOS, import the SDK with @_spi(Internal), then set iamEnabled to true when you configure the SDK. On Android, opt in to InternalRevenueCatAPI, then call iamEnabled(true) on the configuration builder. Every authentication API on Android needs this opt-in.

Swift

// Authentication is behind an internal flag during the beta
@_spi(Internal) import RevenueCat

let configuration = Configuration.Builder(withAPIKey: revenueCatAPIKey)
    .with(iamEnabled: true)

Purchases.configure(with: configuration.build())

Kotlin

// Authentication is behind an internal flag during the beta
@OptIn(InternalRevenueCatAPI::class)
fun configureRevenueCat(context: Context) {
    val configuration = PurchasesConfiguration.Builder(context, revenueCatAPIKey)
        .iamEnabled(true)

    Purchases.configure(configuration.build())
}

On iOS, if your app uses RevenueCat from app extensions, such as widgets, configure the SDK with .with(iamEnabled: true, keychainAccessGroup: "<YOUR_KEYCHAIN_ACCESS_GROUP>") instead. The SDK stores the session in that keychain access group, so your app and its extensions share the same Customer.

When the SDK initializes, it creates an anonymous Customer and starts a session for that Customer. Each sign-in that follows attaches an identity to the Customer. See Anonymous Customers and identities.

2. Listen for authentication events

Set a delegate on Purchases.shared.authentication on iOS, or Purchases.sharedInstance.authentication on Android, to learn when the SDK updates the access token, and when refreshing it fails. Errors from an explicit login call go to that call instead of the delegate.

Swift

final class AuthenticationObserver: NSObject, AuthenticationDelegate {
    // The SDK calls this method when refreshing the access token fails
    // outside of an explicit logIn(using:) call
    func authenticatorDidEncounterError(_ error: PublicError) {
        // Treat earlier access tokens as invalid, and ask the Customer to sign in again
    }

    // Optional. The SDK calls this method each time it updates the access token.
    func authenticatorDidUpdateAccessToken(_ newAccessToken: String?) {
        // Send the new access token to your backend, if it needs one
    }
}

// The SDK doesn't retain its delegate. Keep a strong reference, such as a property
// on your app delegate, for as long as you want to receive events.
let authenticationObserver = AuthenticationObserver()
Purchases.shared.authentication.delegate = authenticationObserver

Kotlin

@OptIn(InternalRevenueCatAPI::class)
class AuthenticationObserver : AuthenticationDelegate {
    // The SDK calls this method when refreshing the access token fails
    // outside of an explicit logIn call
    override fun authenticatorDidEncounterError(error: PurchasesError) {
        // Treat earlier access tokens as invalid, and ask the Customer to sign in again
    }

    // Optional. The SDK calls this method each time it updates the access token.
    override fun authenticatorDidUpdateAccessToken(newAccessToken: String?) {
        // Send the new access token to your backend, if it needs one
    }
}

// The SDK doesn't retain its delegate. Keep a strong reference, such as a property
// on your Application class, for as long as you want to receive events.
val authenticationObserver = AuthenticationObserver()
Purchases.sharedInstance.authentication.delegate = authenticationObserver

The SDK keeps only a weak reference to the delegate. Your app must keep a strong reference to it, or the delegate is released and stops receiving events.

Most apps don't need to read the access token, because the SDK sends it with each of its own requests. Read it when your app calls your own backend, so that the backend can verify the token and identify the Customer. To read the current access token at any time, use currentAccessToken:

Swift

let accessToken = Purchases.shared.authentication.currentAccessToken

Kotlin

val accessToken = Purchases.sharedInstance.authentication.currentAccessToken

3. Send the ID token after each sign-in

After your identity provider signs the Customer in, pass its ID token to logIn(using:) on iOS, or awaitLogIn(identity) on Android. On Android, logIn(identity, callback) is available for code that doesn't use coroutines. RevenueCat verifies the token against your authentication method and returns an access token. RevenueCat never receives the Customer's password, only the ID token.

Pick the tab for the provider of your authentication method.

Apple ID

This example is for iOS only. Apple returns the ID token as Data, so you can pass it to RevenueCat as it is.

Swift

import AuthenticationServices
import SwiftUI

SignInWithAppleButton(.signIn) { request in
    request.requestedScopes = [.email]
} onCompletion: { result in
    switch result {
    case .success(let authorization):
        guard let credential = authorization.credential as? ASAuthorizationAppleIDCredential,
              let tokenData = credential.identityToken else {
            // Apple did not return an ID token
            return
        }
        Purchases.shared.authentication.logIn(using: .signInWithApple(tokenData)) { _, error in
            if let error {
                // Show an authentication error to the Customer
                return
            }
            // The Customer is now identified
        }
    case .failure(let error):
        // Show a sign-in error to the Customer
        break
    }
}

Google ID

This example is for Android only. The iOS SDK doesn't support Google ID sign-in yet. It uses Credential Manager to get the Google ID token.

Kotlin

import androidx.credentials.CredentialManager
import androidx.credentials.GetCredentialRequest
import androidx.credentials.exceptions.GetCredentialException
import com.google.android.libraries.identity.googleid.GetGoogleIdOption
import com.google.android.libraries.identity.googleid.GoogleIdTokenCredential

// Use the client ID of your Google ID authentication method
val googleIdOption = GetGoogleIdOption.Builder()
    .setServerClientId("<YOUR_GOOGLE_OAUTH_CLIENT_ID>")
    .setFilterByAuthorizedAccounts(false)
    .build()
val request = GetCredentialRequest.Builder()
    .addCredentialOption(googleIdOption)
    .build()

lifecycleScope.launch {
    val idToken = try {
        val result = CredentialManager.create(context).getCredential(context, request)
        GoogleIdTokenCredential.createFrom(result.credential.data).idToken
    } catch (e: GetCredentialException) {
        // Show a sign-in error to the Customer
        return@launch
    }

    try {
        Purchases.sharedInstance.authentication.awaitLogIn(Identity.google(idToken.toByteArray()))
        // The Customer is now identified
    } catch (e: PurchasesException) {
        // Show an authentication error to the Customer
    }
}

Firebase

This example uses the Firebase iOS SDK or the Firebase Android SDK, and signs the Customer in with an email address and a password. Enable the Email/Password provider under Authentication → Sign-in method in the Firebase console first. Every Firebase sign-in method returns the same kind of ID token, so the call to RevenueCat stays the same for the others. To create an account instead, call Auth.auth().createUser(withEmail:password:) on iOS, or createUserWithEmailAndPassword on Android.

Swift

import FirebaseAuth

Auth.auth().signIn(withEmail: email, password: password) { result, error in
    if let error {
        // Show a sign-in error to the Customer
        return
    }

    result?.user.getIDToken { idToken, error in
        guard let idToken else {
            // Firebase did not return an ID token
            return
        }

        // Firebase returns the ID token as a String. Convert it to Data.
        Purchases.shared.authentication.logIn(using: .firebase(Data(idToken.utf8))) { _, error in
            if let error {
                // Show an authentication error to the Customer
                return
            }
            // The Customer is now identified
        }
    }
}

Kotlin

import com.google.firebase.FirebaseException
import com.google.firebase.auth.FirebaseAuth
import kotlinx.coroutines.tasks.await

lifecycleScope.launch {
    val idToken = try {
        val result = FirebaseAuth.getInstance().signInWithEmailAndPassword(email, password).await()
        result.user?.getIdToken(false)?.await()?.token
    } catch (e: FirebaseException) {
        // Show a sign-in error to the Customer
        return@launch
    }
    if (idToken == null) {
        // Firebase did not return an ID token
        return@launch
    }

    try {
        // Firebase returns the ID token as a String. Convert it to a ByteArray.
        Purchases.sharedInstance.authentication.awaitLogIn(Identity.firebase(idToken.toByteArray()))
        // The Customer is now identified
    } catch (e: PurchasesException) {
        // Show an authentication error to the Customer
    }
}

A Firebase ID token expires after one hour. getIDToken (getIdToken(false) on Android) refreshes the token first when it is close to its expiration, so call it again for each RevenueCat sign-in instead of storing the token. Password changes, password resets, and email verification stay in Firebase.

OpenID Connect

This example uses Supabase, with the Supabase Swift SDK or the Supabase Kotlin SDK, and signs the Customer in with an email address and a password. Supabase returns an access token instead of a separate ID token, and that access token is the token to send to RevenueCat. Before you start, make sure that your Supabase project signs its tokens with an asymmetric key. See Example issuer URLs.

Swift

import Supabase

// Create the client once, when the app starts. The anon key is safe to ship in your app.
let supabase = SupabaseClient(
    supabaseURL: URL(string: "https://<YOUR_PROJECT_REF>.supabase.co")!,
    supabaseKey: "<YOUR_SUPABASE_ANON_KEY>"
)

do {
    let session = try await supabase.auth.signIn(email: email, password: password)

    // Supabase returns an access token, not an ID token. Send it in place of the ID token.
    let token = session.accessToken

    Purchases.shared.authentication.logIn(using: .oidc(Data(token.utf8))) { _, error in
        if let error {
            // Show an authentication error to the Customer
            return
        }
        // The Customer is now identified
    }
} catch {
    // Show a sign-in error to the Customer
}

Kotlin

import io.github.jan.supabase.auth.Auth
import io.github.jan.supabase.auth.auth
import io.github.jan.supabase.auth.providers.builtin.Email
import io.github.jan.supabase.createSupabaseClient
import io.github.jan.supabase.exceptions.HttpRequestException
import io.github.jan.supabase.exceptions.RestException

// Create the client once, when the app starts. The anon key is safe to ship in your app.
val supabase = createSupabaseClient(
    supabaseUrl = "https://<YOUR_PROJECT_REF>.supabase.co",
    supabaseKey = "<YOUR_SUPABASE_ANON_KEY>",
) {
    install(Auth)
}

lifecycleScope.launch {
    val token = try {
        supabase.auth.signInWith(Email) {
            this.email = email
            this.password = password
        }
        // Supabase returns an access token, not an ID token. Send it in place of the ID token.
        supabase.auth.currentAccessTokenOrNull()
    } catch (e: RestException) {
        // Show a sign-in error to the Customer
        return@launch
    } catch (e: HttpRequestException) {
        // Show a network error to the Customer
        return@launch
    }
    if (token == null) {
        // Supabase did not return a session
        return@launch
    }

    try {
        Purchases.sharedInstance.authentication.awaitLogIn(Identity.oidc(token.toByteArray()))
        // The Customer is now identified
    } catch (e: PurchasesException) {
        // Show an authentication error to the Customer
    }
}

To create an account instead, call supabase.auth.signUp(email:password:) on iOS, or supabase.auth.signUpWith(Email) on Android. If your project requires email confirmation, the Customer has no session until they confirm their email address. To read the current token later, use try await supabase.auth.session.accessToken on iOS, or supabase.auth.currentAccessTokenOrNull() on Android. Supabase refreshes the token first when it is close to its expiration, so read it again for each RevenueCat sign-in instead of storing it.

4. Verify the sign-in

Sign in to your app with a test account. The login call returns no error, and currentAccessToken returns an access token.

If an existing Customer already has the identity that you signed in with, RevenueCat merges the anonymous Customer into the existing one. The purchases of both Customers stay with the existing Customer.

Limitations

• Authentication needs iOS SDK version 5.88.0 or later, or Android SDK version 10.29.0 or later. The feature is behind an internal flag. Support for the hybrid SDKs will follow.
• Apple ID sign-in is available on iOS only, and Google ID sign-in is available on Android only.
• Your app must get an ID token from your identity provider before it can authenticate with RevenueCat. RevenueCat does not show a login screen in your app.

Next steps

• Verify access tokens on your backend to protect the calls between your app and your backend
• Spend in-app currency from your app now that the Customer is authenticated
• Authentication for how the identity provider, the method, and the access token fit together

Was this page helpful?