Articles

See more

Managing access tokens

  • Updated

Access tokens act as keys that enable builders to pull data from third-party applications into their Josef bots. They work alongside Josef’s API to ensure data can travel securely from one platform to the next.

For example, say you have information stored in the popular CRM platform Salesforce and you’d like to pull that information into one of your Josef bots.

At a high level, you’d need to do three things.

  1. In Salesforce, create an application with OAuth authorization settings.
    • Hint: This allows external apps you designate (such as Josef) to access your Salesforce data.
  2. Next, generate an access token in Salesforce and store it in Josef.
  3. Set up API variable(s) in your Josef bot to request data from Salesforce.

This article explains how to do steps 1 and 2. To learn how to do step 3, i.e. set up API variables in your bots, visit this article. 

Third-party system setup

In your third-party system (e.g. Salesforce), you'll first need to create a new ‘application’ with OAuth authorization settings.

To do this, navigate to the platform’s integration application settings, and/or reach out to their Support team.

When setting up the application, ensure that

  1. OAuth access is permitted, and
  2. You authorize the resource to be accessible. Typically this is done by setting the OAuth Scope.

Here’s an example of how to do the above on Salesforce.

Create & edit tokens in Josef

Once you've created the application in your third-party system, you can start creating the access token in Josef.

Builders can manage tokens in Josef by navigating to My account > Integrations > Pull integrations.

Here you can create, edit and connect tokens.

Create new token.png

[Image: A builder's access tokens located in located in My account > Integrations > Pull integrations]

Create tokens

To create a new access token in Josef,

  1. In the top right of Pull integrations, click Create new token.
    • A window will pop up containing all of the fields in which you can input the access token details from your third-party system.
    • Hint: Jump here for an example details of what to include.  
  2. Once you have confirmed and inputted all of the relevant information, click Save when complete.
  3. When ready, click Connect.

Add new authentication .png

[Image: Add new authentication window located in My account > Integrations > Pull integrations]

Token fields

For reference, here’s the functionality of each authentication token field and what you might need to input.

  • Token name
    • You’ll refer to this later in your bot(s) so give it a name you’ll remember! E.g. ‘Salesforce token’
  • Authorisation type
    • The authorisation method your bot will use to access your third-party application. Currently, OAuth 2.0 is the only standard supported.
  • Add authorisation to
    • Determines where the authorisation data will be added when the token makes a request to your application.
  • Refresh token automatically (when available)
    • Access tokens tend to be active for a finite period of time before they expire. By default, we will try to refresh the token for you.
    • Note: Applications differ in how their access tokens refresh. Therefore, we recommend reviewing your application's documentation to learn how and if this is supported.
  • Callback URL 
    • This is the callback URL you will need to add to your application as the redirect URI. This tells your application to redirect you back to Josef after you have authenticated and obtained your token.
  • Grant type
    • This determines how the token is obtained. Please check how your application grants access tokens and select the correct type. Currently, Josef supports token grants via:
      • Authorization Code Grant, or
      • Client Credentials.
  • Parameters / Headers
      • In the Key and Value columns, builders can input parameters or headers. Check with your application to see if any parameters or headers are required to obtain a token.
      • To finalize a new row, click the plus '+' sign in the bottom right.
  • Save
    • Click Save to save the token details.
  • Connect
    • Click Connect to connect to the application to obtain your access token.
  • Delete
    • Click Delete to permanently delete the token. Be careful! This change cannot be reversed.

Edit tokens

To edit an existing token,

  1. Go to My account > Integrations > Push/Pull integrations.
  2. Next, under Active or Inactive/expired, locate the relevant token and click the pencil button on the far right.
  3. Alternatively, to disconnect an active token, click the unlink button on the far right.

Apply tokens to bots

Once your token has been created and connected, you can apply it to API variables in your bot(s). This will then enable the bot to access the relevant data from your third-party system. 

For more information about the different ways API variables retrieve data, and when to use which, please visit this article.

Jump here for an example setup.

Below is a high-level overview of how to apply tokens to your bot's API variables.

  • Note: These instructions simply focus on applying the proper authorisation to already-created API variables. See below for links to guidance on creating the respective API variable types.

 

API response type

In your bot,

  1. Select the relevant message in either List view or Flowchart.
  2. In the Edit message sidebar, click to open the API authorisation token dropdown menu.
  3. Next, select the relevant token.
  4. Done!

For information on how to create an API response type, please visit this article. 

 

Standalone API variable

In your bot,

  1. Open either List view or Flowchart.
  2. Open the Variables library via the tab on the top far right.
  3. Under API request variables, select the relevant variable.
  4. Next, click to open the API authorisation token dropdown menu.
  5. Finally, select the relevant token.
  6. Done!

For information on how to create a standalone API variable, please visit this article. 

Example setup: Salesforce and Microsoft SharePoint

Here’s an example setup of steps 1, 2 and 3 as mentioned in this article’s introduction.

We are:

  1. Creating an application in Salesforce or SharePoint, then
  2. Creating the access token in Josef, then
  3. Applying that access token to an API variable in a Josef bot.

1A. Application setup in Salesforce

To do this,

  1. First, log in to your Salesforce Dashboard.
  2. Navigate to the gear icon at the top right of the page and click Setup.
  3. In the left-hand sidebar, go to Platform Tools > Apps > App Manager.
    • Note: Your Salesforce account must have the necessary admin permissions to access the App Manager. If you don't, please speak to your admin.
  4. Click on the registered application you'd like to use. If you don't already have one, click New Connected App.
  5. Under API (Enable OAuth Settings), mark the "Enable OAuth Settings" checkbox.
  6. Under Callback URL, paste in Josef’s redirect URL:
  7. Select any scopes you'd like to use in your application.
  8. When ready, click Save at the bottom of the page. Salesforce will then provide the Consumer Key and Consumer Secret needed for the next step once you register your application.

Create application in Salesforce.png

[Image: Salesforce user setting up an API (Enable OAuth Settings) application]

1B. Application setup in Microsoft SharePoint

To do this,

  1. First, log in to your Microsoft Azure Portal.
  2. Navigate to App Registrations.
  3. Click New Registration.
  4. Create a Web application and add Josef’s redirect URL:
  5. Under Manager > Certificates and Secrets, generate a Client ID and Client Secret for your application and save those details to be entered into Josef.
  6. Under API permissions, add the permissions you want to provide Josef. For common use cases like reading SharePoint list data, add Microsoft Graph (read access).

[Image: Azure user setting up a new application]

2. Create access token in Josef

We’re halfway there! Now we'll head to the Josef Dashboard to create and store the access token.

  1. Go to My account > Integrations > Pull integrations.
  2. In the top left, click Create a new token.
  3. Next, add the details set out in the table below.
  4. Once you've inputted all the details, click Save to save your token.
  5. Next, click Connect. A Salesforce login portal will appear. Please follow the prompts to log in. If successful, you will be prompted with a "Success! Access authorized" message.

2A. Salesforce token setup

Token name Callback URL  
Salesforce https://auth.joseflegal.com/api/oauth2/callback  
     
Authorisation type Grant type  
OAuth 2.0 Authorization Code Grant  
     
Authorisation data to Parameters  
Request Headers Key Value
  access_token_url https://[insert your unique Salesforce instance].salesforce.com/services/oauth2/token
Refresh token automatically (when available)    
Enabled authorize_url https://[insert your unique Salesforce instance].salesforce.com/services/oauth2/authorize
     
  client_id [insert your Salesforce Consumer Key]
     
  client_secret [insert your Salesforce Consumer Secret]
     
  refresh_token_url https://[insert your unique Salesforce instance ].salesforce.com/services/oauth2/token
     
  response_type code
     
  revoke_token_url https://[insert your unique Salesforce instance].salesforce.com/services/oauth2/revoke

 

[Table: Example Create token setup in Josef]

Create access token.png

[Image: Example Create token setup in the Josef UI]

2B. SharePoint token setup

Token name Callback URL  
Salesforce https://auth.joseflegal.com/api/oauth2/callback  
     
Authorisation type Grant type  
OAuth 2.0 Authorization Code Grant  
     
Authorisation data to Parameters  
Request Headers Key Value
  access_token_url https://login.microsoftonline.com/common/oauth2/v2.0/token
Refresh token automatically (when available)    
Enabled authorize_url https://login.microsoftonline.com/common/oauth2/v2.0/authorize
     
  client_id [insert your Azure application Client ID]
     
  client_secret [insert your Azure application Client Secret]
     
  refresh_token_url https://login.microsoftonline.com/common/oauth2/v2.0/token
     
  response_type code
     
  scope https://joseflegal.sharepoint.com/AllSites.Read offline_access

 

3. Apply access token to API variable

Now, let’s return to the Josef Dashboard and open the bot where we’re planning to use the Salesforce access token.

  • Note: Remember, in order to do this, you’ll first need to have created API variables in your bot. Learn how to do this here.

To apply your new token to your API variable, follow the applicable instructions here depending on whether your data is retrieved as an API response type or a standalone API variable.

Done! Now you'll need to test your bot to ensure everything is working correctly.

Test and troubleshoot

To test whether your access tokens enable data to flow between Josef and your third-party platforms, simply interact with the Preview or live versions of your bot.

If things don't work as expected, be sure to check the following:

  1. Check all of your token details are correct.
  2. Check the API endpoints you’re making a request to are correct.
    • Hint: You can test this outside of Josef, using the application Postman, for example.
  3. Make sure your API variables are set up correctly.
    • Hint: Here's a refresher on what to check.

Get help

If you get stuck, please contact your IT team who may be able to help ensure everything is set up correctly. If you're unable to resolve the issue, we'd be happy to help! Feel free to contact us at support@joseflegal.com.

Happy building!

Related articles