Access Tokens

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-day period, the user will be required to re-authenticate the application’s access.

Access tokens

Access tokens can be further 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 Dataswyft’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 to interact with the API. Create one at https://hatters.dataswift.io/sandbox

The request needed 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 cannot ask for users' owner token or username / password combination. Authenticating users in a 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 will be a refreshed token, x-auth-token in the response header, that you can use to extend the lifetime of the token. The automatic token renewal can be continuously applied for up to 30 days after initial authentication event.