SDK Authentication

Requires SDK 4.10.0 or later

When using data integrations with personalization with Rover, such as using ticketing data in an experience data source from api.rover.io, it is necessary for Rover to securely authenticate the identity of the user according to your backend or identity provider.

We support this by means of an ID Token provided by your Customer Identification and Access Management (CIAM) system or identity provider, cryptographically attesting to a user's identity by encoding it as a JSON Web Token (JWT).

Providing a signed JWT ID Token to Rover allows it to securely verify the user's identity, preventing tampering and exposure of user data.

To learn more, see the JWT.io's introduction.

Server-Side Setup

For tokens issued by your own backend, generate a key pair on your server and use it to generate signed JWT tokens for your users at sign in (and refresh) time. Building and signing tokens can be done using open source libraries.

Generate a Key Pair

First, generate an RSA256 public/private key-pair. The public key will be shared with Rover, and the private key should be stored securely on your backend.

Generate JWT ID Token for the Current User

Second, at user login and token refresh time, generate JWT tokens on your backend, including the ID from your ticketing system (such as Ticketmaster, AXS, SeatGeek, etc.) as a custom claim.

Header Fields

Payload Fields

Claims Fields

Add a custom claim for your ticketing system's ID. This is the ID that Rover will use to enable personalization features.

App-Side Setup

After initializing Rover, register a refresh callback and provide an ID token when the user signs in or an existing session is restored. Set a new token whenever your identity provider refreshes it, and clear it on logout.

Before an authenticated request, Rover checks the stored JWT's exp claim. If it expires within 60 seconds, Rover invokes the refresh callback and waits up to 10 seconds for a setter call. The callback starts your asynchronous refresh; it does not return a token. If no token has been set, Rover does not request a refresh, so provide the initial token before loading personalized data.

Force a refresh when handling this callback rather than returning a cached token that is about to expire. If refresh cannot complete, handle retry or sign-in in your app. Rover continues without the token after the timeout.

Swift:

Whenever your token is updated (such as at login time, or token refresh time), provide your new ID token to the Rover SDK:

Rover.shared.setSDKAuthenticationIDToken("your-id-token")

Then, at logout time, clear the token:

Rover.shared.clearSDKAuthenticationIDToken()

Then, in order to allow Rover to request a token refresh in the event of an expired or soon-to-expire token, register a callback:

Rover.shared.registerTokenRefreshRequestCallback {
    // trigger your token refresh here.  This should trigger a
    // Rover.shared.setSDKAuthenticationIDToken() call.
}

Rover may pause an in-flight request up to 10 seconds while waiting for an updated token, so it is important to call Rover.shared.setSDKAuthenticationIDToken() as soon as the token is available.

Kotlin:

Whenever your token is updated (such as at login time, or token refresh time), provide your new ID token to the Rover SDK:

Rover.shared.setSdkAuthorizationIdToken("your-id-token")

Then, at logout time, clear the token:

Rover.shared.clearSdkAuthorizationIdToken()

Then, in order to allow Rover to request a token refresh in the event of an expired or soon-to-expire token, register a callback:

Rover.shared.registerSdkAuthorizationIdTokenRefreshCallback {
    // trigger your token refresh here.  This should trigger a
    // Rover.shared.setSdkAuthorizationIdToken() call.
}

Rover may pause an in-flight request up to 10 seconds while waiting for an updated token, so it is important to call Rover.shared.setSdkAuthorizationIdToken() as soon as the token is available.

Rover Setup

For tokens issued by your own backend, provide the public key of the key used to sign your tokens to your Rover account manager, so that Rover can configure your account to verify the authenticity of the JWT tokens coming from the app.

Further Reading

• JWT.io's introduction
• JWT.io's open source libraries list
• auth0's ID Token vs Access Token article