Log in with a PDA

The PDA authentication process is OAuth-like and uses Javascript Web Tokens (JWT). Each PDA runs as a separate server and has a publicly-reachable address (such as https://postman.hubat.net). All calls in this documentation are therefore executed against an individual PDA. If you want to test and see how the authentication works, you can use our postman collection here.

Token expiry

Standard authentication token is valid for 72 hours and can be renewed automatically by making a valid backend request to any of the API endpoints. The automatic token renewal can be continuously applied for up to 30 days after initial authentication event. After the 30 days period, the user will be required to re-authenticate the application’s access.

Access tokens

Access tokens can further be grouped into owner-level and application-level.

An Owner-level token is only ever issued to the owner of the PDA and normally used by the PDA dashboard application only.

Application-level tokens are issued to all the different applications that the user chooses to enable on their microserver. These tokens have a much more limited access scope, usually with a read / write access to a single namespace and to data attributes of optionally configured data debit. Access scope for an individual application is configured by the developer on Dataswift’s developer portal.

There are 2 different steps for authenticating users:

  • Requesting a user's owner token

  • Authenticating a user for application token

Owner token authorisation

During development and testing of your application, it's advised to use your sandbox development PDA in order to interact with the API. Create one at https://hatters.dataswift.io/sandbox

The request needed in order to get the owner token is:

GET https://postman.hubat.net/users/access_token

With headers:

username=postman
password=burger-cheese-wine

Response:

{
"accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxLVRGRVo5QVZNZkExRjduckMwTnJEaVJxdXlEd3NKc2loakhvUmNGNm1TQ080TTA4M2s2UkhRUm1MNCs0SlVIdDVRK2w4eWRUckprblJpSnF2MHQwQUtVRzkxcHlkNXRscmJ6N25yR2R5Q21TcXNRPT0iLCJyZXNvdXJjZSI6Im1hcmlvc2Rldjc2Lmh1YmF0Lm5ldCIsImFjY2Vzc1Njb3BlIjoib3duZXIiLCJpc3MiOiJtYXJpb3NkZXY3Ni5odWJhdC5uZXQiLCJleHAiOjE1NzQ5NTAxOTAsImlhdCI6MTU3MjM1ODE5MCwianRpIjoiZjkyZmRmYzQ2YTlmZmU2NWU5ZTBlYWEwNGFjYjRmZjNiMDUzOTRkMzU3NWNlZGFkNTdlYTYzMGQ4YTEzOGQ5ODhiOTZjMTUwYTYyNTI1NjVmNWRlMjIxZjZiZGE5ZjI2N2Q5NDg1YzQwZDQ5NjYyY2MwOGMwODdkM2FlYjU4Y2I3MWUzMzcyZDMyZmE5MDYzMjhmMDQ2NTAzYmZhYzNkMDRlZGNkMWIzMzY3ZDc4NTAwNTJlZWZjYWVhNjRjNWJkZDc0MjFhMjA5OTc3ZjViZGMwMjc1ZTA4Yjc3MmFiMzhlNjhlNjNlMWYwYzVmMWZkNGRkZWY5Y2YzMGNhYTNkYyJ9.e7VwCFS1mUVPSDRHo18EYIPwshmEzfpyO4lHRCDawXWKcWl3paumladGgicE20vJWEK3ibcDtJso88nF-aDG_kK_7nE3qrp98Orjavgz46fq_LITIR41uUKWqt7EkyQCtx_274bT7d23_3tImyJD0sD6odYK-xoatym7ZzA4dMLFhhxKlKQC3E3cXaz83G7F8fFOiItrEnhLqT3jgwvy-7UnaWgFR6j9qPrjdUo7o3v3DKueBjdoC6XxJ6ohdPhtWxa0mXDdN3O8stTjvLCyG62nNPF_sObtu51zTYTrI03JdDenxkXOBjMJV5MjlIAoDEncD3m1MqmXXJyDhXOtjg",
"userId": "6c796c29-fa9e-4678-9c0b-e48956f22bcc"
}

Note: save this token for further usage, see below.

Please note that you can not ask users' owner token or username / password combination. Authenticating users in live environment happens through an OAuth process that you can see in a later step.

Application token authorisation

Please note that this step requires the owner token from the previous step.

GET http://postman.hubat.net/api/v2.6/applications/dataswift-sandbox/access-token

With headers:

x-auth-token = yJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxLVRGRVo5QVZNZkExRjduckMwTnJEaVJxdXlEd3NKc2loakhvUmNGNm1TQ080TTA4M2s2UkhRUm1MNCs0SlVIdDVRK2w4eWRUckprblJpSnF2MHQwQUtVRzkxcHlkNXRscmJ6N25yR2R5Q21TcXNRPT0iLCJyZXNvdXJjZSI6Im1hcmlvc2Rldjc2Lmh1YmF0Lm5ldCIsImFjY2Vzc1Njb3BlIjoib3duZXIiLCJpc3MiOiJtYXJpb3NkZXY3Ni5odWJhdC5uZXQiLCJleHAiOjE1NzQ5NTAxOTAsImlhdCI6MTU3MjM1ODE5MCwianRpIjoiZjkyZmRmYzQ2YTlmZmU2NWU5ZTBlYWEwNGFjYjRmZjNiMDUzOTRkMzU3NWNlZGFkNTdlYTYzMGQ4YTEzOGQ5ODhiOTZjMTUwYTYyNTI1NjVmNWRlMjIxZjZiZGE5ZjI2N2Q5NDg1YzQwZDQ5NjYyY2MwOGMwODdkM2FlYjU4Y2I3MWUzMzcyZDMyZmE5MDYzMjhmMDQ2NTAzYmZhYzNkMDRlZGNkMWIzMzY3ZDc4NTAwNTJlZWZjYWVhNjRjNWJkZDc0MjFhMjA5OTc3ZjViZGMwMjc1ZTA4Yjc3MmFiMzhlNjhlNjNlMWYwYzVmMWZkNGRkZWY5Y2YzMGNhYTNkYyJ9.e7VwCFS1mUVPSDRHo18EYIPwshmEzfpyO4lHRCDawXWKcWl3paumladGgicE20vJWEK3ibcDtJso88nF-aDG_kK_7nE3qrp98Orjavgz46fq_LITIR41uUKWqt7EkyQCtx_274bT7d23_3tImyJD0sD6odYK-xoatym7ZzA4dMLFhhxKlKQC3E3cXaz83G7F8fFOiItrEnhLqT3jgwvy-7UnaWgFR6j9qPrjdUo7o3v3DKueBjdoC6XxJ6ohdPhtWxa0mXDdN3O8stTjvLCyG62nNPF_sObtu51zTYTrI03JdDenxkXOBjMJV5MjlIAoDEncD3m1MqmXXJyDhXOtjg

Response:

{
"accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhcHBsaWNhdGlvblZlcnNpb24iOiIxLjEuMCIsInN1YiI6IjEtMlc1NEErektsdnMwQXdMMm5XVWZNZzQrdCtadFBUQ2tzTWh4SCtmUFRFSUkrbXVoazhsSEVxdTJiaEVmaGpsT2xmR0F3aHhRSExPNDdcL09hUDJ3VkRCV3BaelVuSVpQQWRMTHZOSitUVnltTGd3PT0iLCJhcHBsaWNhdGlvbiI6ImRldmVsb3BlcnMtZGV2IiwiaXNzIjoibWFyaW9zZGV2NzYuaHViYXQubmV0IiwiZXhwIjoxNTc0OTU2MDc3LCJpYXQiOjE1NzIzNjQwNzcsImp0aSI6ImM3MmYxN2U3N2IxMmJkMTNhMWM1ZmFlZDE5MDc5ZWJmMWFhMjFiMTc0MWJiMzVkMDI4NjM5M2I1Mzk0MWUxYjAyNGQyZTNmY2JjMDUyMzIwNjQyYzhkNTM2ZGE0YWMyZWI0NjEzZTlmM2M2MmQwZmIwZDU2Yzk4NmI1YTVmMDBhZTAxZGUzYjVmYmEzNjZkZjcwOTJkZmE3OWI2ZDc4NjRmMmFlZDc1MTE4OTdmMmQzM2ZjOGZjYTZkMmMyMDUzNmQwMDIwMTk2MzNkMWM0MWM4MWM1NTAyNzQ3NGU0NGU0MGRjOTFjOWY2ZTE2MDM4MTA5ZTA1MGFmMWNjZDlmYzkifQ.D3v95Z6mYvfE2khzWiNzmeVmA2n6zSjPKe7WGpKm2Awbr4NnMR0PnX9-ntPgMh0frdPaoUmf6Hm3yIytkpIkYZgB6kTyErI0LVHy0sEJV9SQS0EpP5Ga3FVBU0SBbxPhDx8aYcEJmYLErL_CJwmBTGS_zPJJgPfEO4Fd3JdLjL67oU3UTK9VCji0_aKE4SjkOqbWtczfM4a9fgmAus5OtklVj6wzBr8HYOGbJ8MKKhEQi20Bz-bXJscpijIBnHrns6lQv4DVPraEbKbXdOK4iJII3hiw4aSK6fz42tNu2dB59TKvFAwv2f-U0ap64EodqRIqu-Gqm0icIN452e3xtQ",
"userId": "6c796c29-fa9e-4678-9c0b-e48956f22bcc"
}

With this token you are able to read and write data in the application's namespace. As stated during the introduction of the Authorisation documentation, tokens do expire after 72 hours. In each API request there is going to be a refreshed token, x-auth-token in the response header, that you can use in order to extend the lifetime of the token. The automatic token renewal can be continuously applied for up to 30 days after initial authentication event.

User journey

The user journey is formed by a standard OAuth process. There are 3 steps involved:

  • Send user to PDA login

  • User enters password

  • Receive application token via a callback

Send users to the PDA login

In order to redirect user to the login webpage, it's vital to have user's PDA address, eg. postman.hubat.net. Having that the following redirect has to be executed:

https://<<PDA_NAME>>/#/hatlogin?name=<<APPLICATION_ID>>&redirect=<<REDIRECT>>&fallback=<<FALLBACK>>

Parameter

Meaning

HAT_NAME

The (fully qualified domain) name of the PDA owner, eg. postman.hubat.net

APPLICATION_ID

The id of your application that requests the application token, eg dataswift-sandbox

REDIRECT

A URI which the user will be redirected to in case the authorisation completed successfully. It also contains the application token

FALLBACK

A URI which is being returned in case the authorisation failed

In case of successful authorisation, you can find the application token in the redirect as a query parameter named token.

User enters password

Upon redirecting, users will see familiar, enter your password screen, served by their own PDA:

Note the complete address is served via SSL, contains the name of the PDA as well as the application id, redirect and fallback.

Verify and authenticate user

If the user logs in, they get redirected to the URL provided, with token query parameter appended and containing a RS256-signed JWT token, e.g.:

dataswift-sandbox://apphost?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJleUp3Y205MmFXUmxja2xFSWpvaVkzSmxaR1Z1ZEdsaGJITWlMQ0p3Y205MmFXUmxja3RsZVNJNkluUmxjM1FpZlE9PSIsInJlc291cmNlIjoiaHR0cHM6XC9cL3R3aXR0ZXItcGx1Zy5odWJvZmFsbHRoaW5ncy5jb21cL2F1dGhlbnRpY2F0ZVwvaGF0IiwiYWNjZXNzU2NvcGUiOiJ2YWxpZGF0ZSIsImlzcyI6InRlc3QuaHVib2ZhbGx0aGluZ3MubmV0IiwiZXhwIjoxNDk2OTIyNDIxLCJpYXQiOjE0OTY2NjMyMjEsImp0aSI6ImJlMGYyOTY3Nzk3MDc5MThkOWEzZDYxOGRkOTg5MGQ2MDRkMGRlMTg2MDEzYjE2MTYwNmU5ZmVmZDgxYmRjMmJjZTVjZDE2NWE2MTAxZWU0ZTU1NzJiYmVkMjIzYTRmOWRiNDcyNDc5YTBhMDY4ODkwNGZhN2QxZTUxNThjMzJlMzNhOTY5YWRmZTdkYzc4MmI4ODk1ZjJhY2E2MDMyOTM3NTRmZWJhNGUxNzNhMzE3ZmQ3ZDk1OTQyYzRmNTRkMWM3YWM5YzI3OThiYTZhODZhZWEzYTBmMzQ4OTI4MDJlZDQ4ZmU1NWEwMmUyYjgzNDJlODUxM2E2MTEzODBmYWIifQ.4thestm60WrueQmlBxDRp37uGKUtGpx6PeE4lB_xzlRmxrQ67vk1xFT1nyvFvZfGLnkq51GaB5UsA_zbMhhATC8dDWX1FjNiiRfjAj5r5LFTZW-hRnI0LodzyEJ8YMFbG_t-epSo_KsIig4Ardnzt5VioLwmdr37YJLHxmn1033ArBocVqsAg_pH8DghsaRbzdDWXHcwnCO5wtHJn0RVvAdXG5TKhegs3AuneYktTktvYjj__o66kn8DROKsqeICqCAJTxuJFQpBdoOlPXGgfUW4VQ1wcFC91MoPns1I04otuo6wglCXE576NnLHL3Q7ZKZ_CTVqmnlNg5txC_pnog

The token decodes to:

The Header:

{
"typ": "JWT",
"alg": "RS256"
}

The Payload:

{
"applicationVersion": "1.1.0",
"sub": "1-2W54A+zKlvs0AwL2nWUfMg4+t+ZtPTCksMhxH+fPTEII+muhk8lHEqu2bhEfhjlOlfGAwhxQHLO47/OaP2wVDBWpZzUnIZPAdLLvNJ+TVymLgw==",
"application": "developers-dev",
"iss": "postman.hubat.net",
"exp": 1574956077,
"iat": 1572364077,
"jti": "c72f17e77b12bd13a1c5faed19079ebf1aa21b1741bb35d0286393b53941e1b024d2e3fcbc052320642c8d536da4ac2eb4613e9f3c62d0fb0d56c986b5a5f00ae01de3b5fba366df7092dfa79b6d7864f2aed7511897f2d33fc8fca6d2c20536d002019633d1c41c81c55027474e44e40dc91c9f6e16038109e050af1ccd9fc9"
}

The key parts of the Payload are:

  • The applicationVersion, is the version of the app that generated the token

  • The application, is the application id that generated the token, it must match the application that requested

    application token

  • The iss (issuer), which is the address of the PDA that has created the token and that you should be logging in

  • The exp (expiry) Unix timestamp the token was created, defining whether the token is still valid

  • The iat (issued at time) Unix timestamp the token was issued, used to calculate if 30 days have lapsed since the

    time the token was first issued

In case you want to verify the signature of the token, which is generated from the token and the private key of the PDA, by accessing the /publickey endpoint of the PDA (e.g. https://postman.hubat.net/publickey). The precise handling of tokens with asymmetric keys will depend on your library, however you need to make sure that your library supports RS256 keys.

Signature validation is useful in cases you need to verify that the token has not been tampered in any way.

A few useful resources to help you with JWT tokens:

jwt.io contains a very useful tool for token debugging while in development as well as listing all the major JWT libraries.

JWT libraries are available in all major programming languages and most major frameworks implement wrappers for them. You should be careful in verifying the library of your choice is up to date and does not have reported security flaws in it.