Developer Chat Apache 2.0 License Objective-C/Swift Web Support


Ongoing Access

Introduction

Ongoing Access allows continuous access to user’s data without the use of digi.me app after initial consent has been given*.

From developer perspective the authorization process is almost identical to regular authorization. Under the hood we use OAuth 2.0 with JWT and JWS with RSA signing and verification to issue a medium lived, refreshable OAuth token, which is used to re-query user’s data without the need to leave your app.

Here is a simplified sequence diagram of how the OAuth flow is implemented:

The SDK handles all of this for you.

Ongoing Access is for you if:

  • You need regular access to user’s data
  • You are using an ongoing contract

* refreshTokens used to refresh accessTokens do eventually expire (for example - 30 days). When this happens, user will need to be directed back to digi.me app for re-authorization.

Example

We have built an example app called “Genrefy” which can be accessed from examples folder. It uses Ongoing Access to show the user their most listened to genres of music on Spotify. The app is already configured. Simply:

  1. Head on over to the Dev Portal to request an appId

  2. Replace YOUR_APP_ID string with the appId you get

  3. Build and Run.

How to use

Simply use the new authorizeOngoingAccess method on an instance of DMEPullClient:

Objective-c
[pullClient authorizeOngoingAccessWithСompletion:^(DMESession * _Nullable session, DMEOAuthToken * _Nullable oAuthToken, NSError * _Nullable error) {
    //you may now fetch account list / fileList / session Data
}];
Swift
pullClient.authorizeOngoingAccess(completion: { session, oAuthToken, error
    //you may now fetch account list / fileList / session Data
})

See Fetching Data for more details on post-consent steps.

You may notice that upon completion of this method, the SDK supplies a DMEOAuthToken. This is key to access restoration and we recommend you store this - you will need it later.

Our recommendation would be to save it to keychain.

Access Restoration

If you have previously obtained user’s consent, and are in posession of a DMEOAuthToken, you can get data from your users without them having to leave your app.

To do this, simply call the following method on a new DMEPullClient instance:

Objective-c
[pullClient authorizeOngoingAccessWithScope:nil oAuthToken:oAuthToken completion:^(DMESession * _Nullable session, DMEOAuthToken * _Nullable oAuthToken, NSError * _Nullable error) {
    //you may now fetch account list / fileList / session Data once again
}];
Swift
pullClient.authorizeOngoingAccess(scope: nil, oAuthToken: oAuthToken, completion: { session, oAuthToken, error
    //you may now fetch account list / fileList / session Data once again
})

One important thing to note here - the DMEAuthToken returned in completion may not be the same token you have passed in. This is because the SDK will try to automatically refresh an accessToken using a refreshToken (both of these contained in DMEOAuthToken), generating a new DMEOAuthToken. This means you should replace your old token with the one you receive in completion.

Under the hood the SDK will trigger data query using the DMEOAuthToken which, if valid, will start preparing user’s protected resources for access. This time however, the user will remain in your app.

Configuration Options

There is a new property available on DMEPullConfiguration object - autoRecoverExpiredCredentials. This defaults to true, which means that if the refreshToken contained in DMEOAuthToken has expired, the user will be directed to the digi.me app, so that this can be regenerated.

If you wish to direct the user back to digi.me app manually, set this property to:

Objective-c
configuration.autoRecoverExpiredCredentials = NO;
Swift
configuration.autoRecoverExpiredCredentials = false;

When set to false, the SDK will return an AuthErrorOAuthTokenExpired error in completion.

Anything else?

In the examples above we have used a method with a scope parameter. Scoping is useful when you want to only access a subset of data, such as data generated after certain date. If you would like to learn more - see Scoping.

If you need help setting up the rest of the flow, or simply more detail, then head on over to Getting Started.