PDA Auth Guide

The goal was to implement PDA Auth screens in a simplified style with less visual clutter.

PDA Auth includes the following screens:

  • email/password collection for signup

  • email/password collection for login

  • password recovery and reset screen

  • HMIC screen

Registration

To use the new PDA Auth flow you will first need to redirect the user where they can give their consent to complete the registration.

You can do this by building the signup URL using your application_id and redirect_uri, see below for an example, these parameters are required:

https://auth.dataswift.io/services/signup?
application_id=<application-id>
&redirect_uri=<redirect-uri>

There are two optional query parameters as well:

  • lang

    • Defaults to en.

    • If you pass a different country code by using lang=<country-code>,

      the application will appear localized to the requested language, for example: lang=pt

  • skip_deps

    • Defaults to false.

    • This flag allows control over how the platform handles downline dependencies of your

      application. If, for example, your application depends on a DataPlug to provide data that

      your application can use, the default behaviour of skip_deps=false will automatically send

      the user to the appropriate service to enable the DataPlug.

    • We now support an option for the developer to skip the latter step by using skip_deps=true

      flag passed to the API as a query parameter. When the flag is added, the platform will create

      a PDA for the user, but will skip data synchronization setup. In this case, it is up to the developer

      to decide how they want to handle data synchronization setup in the future.

Upon successful signup, the user will be redirected back to your application with the authentication token attached. This should be stored for subsequent API calls:

test-app://authenticate?token=eyJ0eXAiOiJKV1Qi….

Authentication

To use PDA Auth authorization, you will need to redirect the user where they can enter their password and complete the process.

You’ll need to build the URL using your Application ID, and a redirect URI. The URL will look similar to this:

https://auth.dataswift.io/services/login?
application_id=<application-id>
&redirect_uri=<redirect-uri>

Optional configuration query parameters:

  • lang

    • Defaults to en.

    • If you pass a different country code by using lang=<country-code>,

      the application will appear localized to the requested language, for example: lang=pt

Upon successful login, the server will verify if the application has been granted all the permissions it needs. If not, the user will need to do so for the app to access their Personal Data Account.

Lastly, the user will be redirected back to your application with the authentication token attached. This should be stored for subsequent API calls:

test-app://authenticate?token=eyJ0eXAiOiJKV1Qi….

Email Verification

Upon successful registration, the user will receive an email to verify their email address and create a password. The user will be redirected to PDA Dashboard by clicking the link with the unique token.

https://<pda-user-url>/auth/verify-email/<verification-token>?
email=<email-address>
&application_id=<application-id>
&redirect_uri=<redirect-uri>

Password Recovery

If the user doesn’t remember their password, they can reset it using their email address, by navigating to Forgot password? page. They will receive the email below.

Password Reset

If the email address is associated with an active account, the user will receive the unique reset link.

https://<pda-user-url>/auth/change-password/<reset-token>?
email=<email-address>
&application_id=<application-id>
&redirect_uri=<redirect-uri>

Migration from BaaS or DaaS

Please note: BaaS and DaaS flow will be deprecated and removed in the future. There is no exact timeline currently.

Backend-as-a-Service

If you are currently using the Backend-as-a-Service (BaaS) flow currently, you can migrate to PDA Auth by following this guide.

You are currently using the following signup link:

https://hatters.dataswift.io/services/baas/signup?
email=<email-address>
&hat_name=<hat-name>
&application_id=<application-id>
&redirect_uri=<redirect-uri>

You will need to update your signup link to, using the same application_id and redirect_uri

https://auth.dataswift.io/services/signup?
email=<email-address>
&application_id=<application-id>
&redirect_uri=<redirect-uri>

Data-as-a-Service

If you are currently using the Data-as-a-Service (DaaS) flow currently, you can migrate to PDA Auth by following this guide.

You are currently using the following signup link:

https://hatters.dataswift.io/services/daas/signup?
email=<email-address>
&application_id=<application-id>
&redirect_uri=<redirect-uri>

You will need to update your signup link to, using the same application_id and redirect_uri:

https://auth.dataswift.io/services/signup?
email=<email-address>
&application_id=<application-id>
&redirect_uri=<redirect-uri>

Please note: the email query parameter is now optional, if you choose to collect the email will be automatically filled in the next screen, if you do not collect it, we will explicitly ask these to provide it.