Data Plugand include information such as version, name, textual description, potentially with no screenshots as plugs typically do not have a user interface. To give a PDA owner an idea of what data it pulls in, it would include a "data preview" with some sample data. Permissions would say that the application has rights to write to the
Externalsetup, indicating the address to redirect user to. Finally, data fetching authorization can be disabled at the source, therefore to make sure that a plug is still active, an
Externalstatus check is needed.
Applicationwith platform set to iOS and list information similar to Data Plugs, but screenshots should also be provided. Notables is an example of where the service consists of a user application as well as a backend service handling requests to share notables on social media as well as take them down. It therefore needs permissions to 1) write data to
rumpelnamespace, where notables are stored, 2) read data from
rumpelnamespace to render all notables as well as owner's profile information, 3) set up data plugs and 4) associated data debit, which allows backend service to access shared notables. Setup in this case is also external — PDA owner needs to be redirected to the Notables application. The URL the owner gets redirected to include access token as a query parameter. Finally, external status check ensures that the backend can periodically get a new access token to fetch data from the PDA.
App— a full, external application that uses HAT as a backend
Data Plug— a Data Plug that pulls data in from a remote source on behalf of the user
Tool— a tool that has UI integrated within a PDA application, but may need to rely on a separate backend service for processing data
Internalsetup happens without leaving the app, where all controls are presented in the controlling UI, while External is an external process, where the user is sent off to another interface to set up. In both cases, “Permissions” needs an explicit approval step.
x-auth-tokenencoding user's token in a header
statusUrl, checking the status reported by the remote system
application nameand an allowed
redirect urlfor the user to be sent to complete authentication. If you do not have these details, you can put any
redirect url. The authentication token you will receive from the HAT will reflect the settings in the Application manifest. Your own application is tasked with choosing the correct
redirect urlif the url varies across different platforms.
https://<<HAT_NAME>>/hatlogin?name=<<APPLICATION_NAME>>&redirect=<<REDIRECT_URL>>endpoint of the PDA, where:
<<HAT_NAME>>is the (fully qualified domain) user's PDA name
<<APPLICATION_NAME>>is the name of your application as explained above
<<REDIRECT_URL>>is the URL where the usr should be sent for completing authentication
tokenquery parameter appended and containing a RS256-signed JWT token, e.g.:
resource, which you must verify to check the token was intended for your service
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
applicationwhich defines the rights of the token — application would not get permissions higher than pre-approved
/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 RS256 keys.
/api/v2.6/applications— returns the full list of approved applications
Internalstatus checks, checks if the required data debit is setup and active, in which case the app is considered “active”.
Externalstatus checks, generates the corresponding application token and makes an API request to the configured endpoint internally,
/api/v2.6/applications/:application-idbut this shouldn’t be needed in most cases. It will have exactly the same information and format as a single item in the list returned by
setupendpoint, for both
Internal, there is no further setup that should or could be carried out.
External, configuration may include a default (web) url, an iOS-specific or an Android-specific url identifying the application to be launched. In this case the url is chosen by the UI depending on where it is running, i.e. an iOS application should not choose to redirect the user to an Android-specific url. To log the user in, they should then be redirected to
/api/v2.6/applications/:application/disable. This takes care of recording the fact on the PDA, disabling any data debits and stops tokens issued to that application from working with the PDA.
Externalsetup flow, you may need the application’s token, which can be obtained by calling
/api/v2.6/applications/:application/access-token. This endpoint is, however, very restricted and by default for any application, including those with “Owner” level access, will return