# User Journeys

## 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

To redirect the 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 DA owner, e.g. **postman.hubat.net**                                                        |
| APPLICATION\_ID | The id of your application that requests the application token, e.g. **dataswift-sandbox**                                           |
| REDIRECT        | A URI to which the user will be redirected when the authorisation is 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 a familiar "enter your password" screen, served by their own PDA:

![](/files/0666SyL8E0yEl1CF3xXs)

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:

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

The Payload:

```javascript
{
  "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 the application token
* The `iss` (issuer) 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

You can 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 case you need to verify that the token has not been tampered with in any way.

A few useful resources to help you with JWT tokens:

[jwt.io](https://jwt.io) contains a very useful tool for token debugging while in development as well as listing all the major JWT libraries.

![](/files/xJYr7PE14sxyAfD48LjL)

JWT libraries [are available](https://jwt.io) in all major programming languages and most major frameworks implement wrappers for them. You should be careful in verifying that the library of your choice is up to date and does not have reported security flaws.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dataswyft.com/build/advanced-topics/pda-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.