HAT-API-Androidprovides features that enable your app to
authenticatewith the PDA,
PDA, fetch and setup
Data debitsand use advanced features like
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.
The steps to logging in with a PDA are:
- 1.You send the user to
/hatloginendpoint on their PDA, such as
- 2.The PDA owner enters their login details in the login screen and verifies the service they are logging into.
- 3.The user is redirected back to the address you have provided with authentication token in a query parameter. You validate the token against the PDA’s public key to confirm that the user owns the specific PDA and log them in.
To log in the user with their PDA, you need to ask for their PDA address. Depending on the status of your app within the HAT ecosystem you may also have a specific
application name, an allowed
success redirect urland an allowed
fallback redirect urlto which the user is sent to complete authentication. If you do not have these details, you can put any
success redirect urland
fallback redirect url. However, the authentication token you receive will not grant you any permissions to do any operations on the PDA; it can only verify that the token really came from the PDA.
Androidapplication that means asking user to type the
DA Address. Here's a very simple example:
In the above image, the user is being asked to fill in the HAT address,
postman, and select a domain,
.hubat.net. There can be other domains as well, e.g.:
hubofallthings.net. We thought that splitting the address and the domain made for a better UX, but this is not a requirement for your app. You could have one
EditTextthat the user will have to type the full address,
Having asked the user to fill in the
DA address, e.g.
postman.hubat.net, you have to send them to
"https://$hatAddress/#/hatlogin?name=$applicationName&redirect=$redirectURL&fallback=$fallbackRedirectURL"endpoint of the
$hatAddressis the PDA's (fully qualified domain) address, e.g.
$applicationNameis the name of your application on the HAT. This is defined once when you complete the form to create a new application. e.g
$redirectURLis the URL to which the user should be sent after completing authentication. Optional. For an
Androidapplication that would probably be:
$applicationName://successand has to be added in the
AndroidManifest.xmlfile ofthe project in intent-filter of an Activity as a data with
$fallbackRedirectURLis the URL to which the user should be sent in case the authentication has failed. Optional.For an
Androidapplication that would probably be:
$applicationName://failedand has to be added in the
AndroidManifest.xmlfile of the project in intent-filter of an Activity as a data with
Androidapplication, in order to redirect the user to an existing
DA addressand proceed to the next step, we have to use
WebViewto open the
To achieve this with
WebViewyou have to create an xml file with
WebViewelement and an activity with the login address described above,
"https://$hatAddress/#/hatlogin?name=$applicationName&redirect=$redirectURL&fallback=$fallbackRedirectURL", and then via a
Activity, present the WebView layout. e.g.:
val mWebView = findViewById(R.id.webView)
That will launch WebView within the app and load the url specified.
In the next step, users will be asked to fill in the
passwordfor the particular
This screen cannot be modified in any way. Users have to insert the password for the specified PDA and tap
Note that the complete address is served via SSL, contains the PDA's name as well as the application parameters –
fallback redirect url.
LOGINthe authentication process will begin.
PDAwill use one of the two
redirect urlthat were included in the
success redirectif everything went ok or
fallbackRedirectURLif an error occurred. The application has to know how to respond in both scenarios.
To achieve that, we have to add the
AndroidManifestfile in the project.
To add them to the
AndroidManifestfile, you have to add the Key
URL Typesas a data.
<activity name="MainActivity" >
This will be your app's url scheme. That means every time
Androidintercepts a URL starting with this value, like
test://hostwill hand the process to your app, which will be responsible to either launch or not.
If the user logs in, they get redirected to the URL provided, with
tokenquery parameter appended and containing a
RS256-signed JWTtoken, e.g.:
The token will decode to something like this:
The key parts of the Payload are:
applicationVersion, the version of the app on HAT
sub(subject), the subject of the token
application, the application name that requested the token
iss(issuer), which is the address of the PDA that has created the token and that you should be logging in
exp(expiry) time of the token as a Unix timestamp, defining whether the token is still valid
iat(issued at time) time that the token has been created as a Unix timestamp, defining whether the token is still valid. Token expires after 30 days of the issued at date, no matter if a refreshed token has been received from PDA.
jti(JWT ID) the ID of the token
The Signature, which is generated from the token and the private key of the PDA. The signature must be verified to verify that the token has not been tampered with. A PDA’s public key can be accessed at the
/publickeyendpoint 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
When you have received a successful redirect from
PDA, you can check with
HAT API Androidand verity the user. To do so you simply have to call:
applicationNameis the name of the application that sent the user to log in
urlis the full url that returned from the
PDA, like the example at the beginning of step 3.
successis a callback to execute when the library has successfully authorised the user. You can use this callback to dismiss
WebViewactivity, save the values needed and navigate to the next
failedis a callback to execute when the library couldn't authorise the user. You can use this callback to dismiss
WebViewactivity and show an error message to the user.
Having received the success callback you have to save the token, ALWAYS use
Encryptionto save the token. DO NOT save it in any non-encrypted database. It's also a good idea to save the full
PDA Address, as you will need it many times to communicate with the PDA. You can store the values in SharedPreferences in Private mode.
As soon as you save the token you are free to navigate to your next
If the authentication fails, you will be redirected to the fallback url. In that case you should dismiss
WebViewActivity and then update the UI or show an error message back to the user.
You can dismiss the browser from the viewController that presented originally the
Activity, like this: