crtl+shift+\` on Windows or command+shift+\` on Mac.
@@ -18,27 +18,43 @@ npm install --save @oneblink/sdk
This will install the OneBlink SDK to that project. If this is your first package install, it will create a folder named `node_modules` and create 2 files named `package.json` and `package-lock.json`.
-If you haven't seen these files and folder before, you can read this explanation below, if you have, skip to the next heading.
+If you haven't seen these files and folder before, you can read this explanation below. If you have, skip to the next heading.
-`node_modules` is where all the code for the installed packages is stored. `package.json` is used to provide important information regarding the project. It shows you the name of the project, showing installed dependencies and developer dependencies. It can show you the version of the current project and provide you a place to write scripts that node can run for you. `package-lock.json` that shows all of the required code to install specific packages, this includes all of that packages dependencies so you can have a full guide to what has been installed. This helps node understand what has been installed and changed only necessary data on later installations.
+`node_modules` is where all the code for the installed packages is stored. `package.json` is used to provide important information regarding the project. It shows you the name of the project, installed dependencies and developer dependencies. It can display the version of the current project and provide you a place to write scripts that node can run for you. `package-lock.json` shows all of the required code to install specific packages, this includes all of that packages dependencies so you can have a full guide to what has been installed. This helps Node understand what has been installed and change only necessary data on later installations.
Now that we have installed the SDK, we can go obtain some developer keys from the Console!
## Obtaining Developer Keys
-In order to use the SDK, we will need developer keys which we can generate on the Console. You have to ensure you have the correct role permissions in order to do so. This can be set under 'roles' on the side bar under the 'advanced' heading. Once in, you can edit an existing role by clicking the three buttons or you can add a new role by hitting the orange button in the bottom right.
+In order to use the SDK, we will need a developer key.
-A modal should pop up. In here, you can set the name that you would like the key to be called. You can then select the privileges you would like the key to have too. In this case, we will need Forms, and API Deployment, much like this screenshot:
+There are two types of keys we can create:
+
+- Role Based Key
+- Submission Data Key
+
+In this tutorial, we are going to create a Submission Data Key. We can generate these on the Console. You must have sufficient role permissions in order to do so. This can be set under 'Roles' on the side bar under the 'Advanced' heading. Once in, you can edit an existing role by clicking the three buttons or you can add a new role by hitting the orange button in the bottom right.
+
+After you have sufficient role permissions, we will now navigate to "Developer Keys" under the "Developer" heading on the side bar.
+On this page, we will hit the add button in the bottom right. A modal should pop up. In here, you can set the name that you would like the key to be called. You can select the type of key you want to generate. If you select the "Role Based Key", you can select the role you want to associate with the key. We will select "Submission Data Key". You can see this in the screenshot below:
-After generating this key, you should see something like this:
+After generating this key, a modal will appear that includes your Access Key and your Secret Key. Your Secret Key will be inaccessible after this point, as the warnings indicate, so make sure you save your key details somewhere secure. After closing that modal, you will see your key in the list as so:
-I've hidden my keys obviously but you should have 2 rows of data, 1 visible but the other is hidden with dots. Now that we have the key, let us jump back into the code.
+After creating your key, you will need to associate it with an app to allow the key to be used. You can do this by navigating to "Apps" on the side bar. Open the app you would like to associate the key with. On the Summary screen, you can see this card towards the bottom of the page.
+
+
+
+You can hit "Assign Developer Key" which will open the modal below:
+
+
+
+You can select your new Submission Data Key then hit save. This will add it to your list of allowed Developer Keys for the app. Now, we can get into updating our code!
-## Updating your Code
+## Updating the Code
Now we need to go into our code and create some checks to ensure that the user is valid. The steps we will go through to achieve this are:
@@ -49,7 +65,7 @@ Now let us go down the list!
### Create a new FormsApp Object
-Firstly, we need to use the FormsApp object from the OneBlink SDK so add this code to the top of your file you are working on:
+Firstly, we need to use the FormsApp object from the OneBlink SDK. Let us add this code to the top of our file we are working on:
```js
const formsApp = require("@oneblink/sdk/tenants/oneblink");
@@ -76,7 +92,7 @@ replacing the values with the respective values from the Console. You can place
### Use the VerifyJWT function from FormsApp
-After this, in your function at the very beginning, you can use this code:
+After this, in your function, you can use this code to verify your user:
```js
const authenticationHeader = req.headers.authorization
@@ -91,6 +107,7 @@ After this, in your function at the very beginning, you can use this code:
```
Alright so let's break this down.
-First, we are grabbing the authentication header from the request that was sent to the API from the request's header. After this, we are checking to see if the header is of type string. If it is not, the user has NOT logged in! That means we cannot authenticate this user so we return a 400 on the `res` object by `setPayload(400)` to return a 400 HTTP code and return `setPayload({message: 'Error, no user logged in. User must be logged in.'})` as the payload with an error message. If there is an authentication header, we can split it so we grab the JWT token. After this, then we can run the [verifyJWT()](https://oneblink.github.io/sdk-node-js/classes/oneblink.FormsApps.html#verifyJWT) function with the token to verify who the user is!
+First, we are grabbing the authentication header from the request header that was sent to the API. After this, we are checking to see if the header is of type string. If it is not, the user has NOT logged in! That means we cannot authenticate them! In this case, we will return a 400 on the `res` object with `setPayload(400)` to return a 400 HTTP code and use `setPayload({message: 'Error, no user logged in. User must be logged in.'})` as the payload with an error message.
+If there is an authentication header, we can split it based on white spaces and grab the value at the '1' index. This will provide us with the JWT token. After this, we can run the function [verifyJWT()](https://oneblink.github.io/sdk-node-js/classes/oneblink.FormsApps.html#verifyJWT) with the token to verify who the user is!
After verifying the JWT, you are free to continue doing what you need to with your API! There are other OneBlink functions that can assist you in other JWT functions. For example, you can use our `userService` from `@oneblink/sdk-core` to get the user Profile of the specific user who is logged in.
diff --git a/docs/pics/AddingDeveloperKeyToApp.png b/docs/pics/AddingDeveloperKeyToApp.png
new file mode 100644
index 0000000000000000000000000000000000000000..482d88b2a2aab0bbe4614e55d55c70c8dc9ecafd
GIT binary patch
literal 15641
zcmc(G2T)Vr+h!CM5dlE~=}J`)klw4(n}UQ6O7Fcxhzf}GCcXC-dM^Q_hmz1cM0yED
zdJAF0@BjU0cK6$z+1dGa_Rgfd=RLQ)=bn4+bDsA(!5>uR2p&;B0ssI63i9vO0RS8!
z?Ek}ucd_3~^{KhopF1wkGjanfMU`s=W<5UyV9F$?nmW06uNZ^M
z5yFmrehKNkDjhe*`>I(Ak+%||i%e8s1$5KDDIU=+Tw~A4P_QL%)8Vx|<~lM4F^xm?
zh`yQ(LF;+ghmi8|)1z%pCB;O(O%SQkXr26Qq91WTK;%9TTNCp_rEZlR?