Authentication¶

The Mobile SDK takes an access token issued by Tapkey to log in users within the SDK. The Mobile SDK supports multiple users being logged in at the same time. Getting an access token from Tapkey is up to the implementing application and can be achieved in multiple ways.

Retrieving an Access Token¶

Most applications will either use the Token Exchange or the Authorization Code with PKCE grant type to retrieve an access token from Tapkey. A few of the most common scenarios are outlined in the following:

• I have my own users and want to offer them access to Tapkey locks I control (e.g. car sharing, office rentals). → Token Exchange
• I want to act on behalf of a user of the Tapkey app (e.g. home automation). → Authorization Code with PKCE
• I want to offer an on-top service for users of the Tapkey app (e.g. delivery, cleaning, repairs). → Authorization Code with PKCE
• I do not have my own users but want to build a solution that can be used as an alternative to or in parallel with the Tapkey app. → Authorization Code with PKCE

Implementing the correct OAuth flow and retrieving an access token from Tapkey is task of the implementing application and outside the scope of the Mobile SDK. The Mobile SDK will only accept an access token to log in a user. It is strongly recommended to use an existing OAuth library rather than implementing one of the grant types from scratch.¹

Logging in a User¶

Once an access token has been retrieved, it has to be passed to the SDK to log in a user:

Promise<String> userId = userManager.logInAsync(accessToken, cancellationToken);

let userId: TkPromise<String> = userManager.logInAsync(
    accessToken: accessToken,
    cancellationToken: TKMCancellationTokens.None)

Refreshing an Access Token¶

Prior to logging in users, a token refresh handler must be registered with the TapkeyServiceFactory. The token refresh handler will be called every time a user's access token has expired and needs to be refreshed.

// In Application.onCreate():
TapkeyServiceFactoryBuilder b = new TapkeyServiceFactoryBuilder(this);
b.setTokenRefreshHandler(new TokenRefreshHandler() { ... });
b.build();

// Build service factory in AppDelegate's willFinishLaunchingWithOptions
self.tapkeyServiceFactory = TKMServiceFactoryBuilder()
    .setTokenRefreshHandler(SampleTokenRefreshHandler())
    .build()

Logging Out a User¶

Promise<Void> result = userManager.logOutAsync(userId, CancellationTokens.None);

_ = userManager.logOutAsync(userId: userId, cancellationToken: TKMCancellationTokens.None)