# Set up a generic OAuth integration

OAuth is a service that is used to grant access to applications without using a password. In FlowBuilder, you can now set up a generic OAuth integration to make authenticated requests to third-party applications.

 

### Requirements

* A [MessageBird account](https://dashboard.messagebird.com/en/sign-up)
* [Flow Builder](https://dashboard.messagebird.com/en/flow-builder)
* A [Teamleader account](https://app.teamleader.eu/?gotologin\&intended=%2Foauth2%2Fauthorize%3Fredirect_uri%3Dhttps%253A%252F%252Fmarketplace.teamleader.eu%252Flogin%252Fcallback%26state%3D3f05e3d62ac93e4fd2a464a163eb2f5a%26scope%3D%26response_type%3Dcode%26approval_prompt%3Dauto%26client_id%3De74869f17778ab97ac020a0767b93ba8) (optional)
* A [Zoho account](http://zoho.eu) (optional)

 

## Step one: Create a new configuration

1. Go to the [integrations page](https://dashboard.messagebird.com/en-us/integrations) in your [MessageBird Dashboard](https://dashboard.messagebird.com/)
2. Under OAuth, click **Add integration**. A form will appear with fields that you need to fill in to set up a new OAuth2 integration
3. Enter a **Name**. Choose a descriptive name for this integration that makes it easy to find and identify. This name will be shown in a dropdown in Flow Builder when you use the integration
4. Enter the **OAuth client ID**. This is the client ID provided by the third-party application. Copy and paste it from the app settings
5. Enter the **OAuth client secret**. This is the client secret provided by the third-party application. Copy and paste it from the app settings
6. Enter **OAuth Scopes**. This defines the resources that you will be allowed to access. To determine which scopes you may need, see the documentation of the application you are adding the integration for
7. Enter the **OAuth endpoint authorization URL**. This Is the URL where you will login to authorize FlowBuilder to access the application. This can be found in the documentation of the application. See Table 1 below for the authorization URLs of some commonly used applications, or copy and paste it from the app settings
8. Enter the **OAuth endpoint authorization token**. This is the URL that FlowBuilder will call in order to exchange your authorization code with an access token. This can be found in the documentation of the application. See Table 1 below for the authorization tokens of some commonly used applications, or copy and paste it from the app settings.\
   \
   Table 1<br>

   | **Application** | **Authorization URL**                                                                                                                              | **Authorization Token**                                                                                             |
   | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
   | **Google**      | <https://accounts.google.com/o/oauth2/auth>                                                                                                        | <https://oauth2.googleapis.com/token>                                                                               |
   | **Zoho**        | <p><https://accounts.zoho.com/oauth/v2/auth></p><p><em>or</em></p><p><https://accounts.zoho.eu/oauth/v2/auth></p><p>(depending on data center)</p> | <p><https://accounts.zoho.com/oauth/v2/token></p><p><em>or</em></p><p><https://accounts.zoho.eu/oauth/v2/token></p> |
   | **Intercom**    | <https://app.intercom.com/oauth>                                                                                                                   | <https://api.intercom.io/auth/eagle/token>                                                                          |
   | **Teamleader**  | <https://app.teamleader.eu/oauth2/authorize>                                                                                                       | <https://app.teamleader.eu/oauth2/access\\_token>                                                                   |

   <br>
9. Check the **User authorization callback URL**. This field is automatically filled for you. The authorization callback URL, also called a redirect URL, should be copied and pasted to your application so that after successful login, the application redirects back to MessageBird in order for us to complete the integration setup<br>
10. After filling in the fields and copying the callback URL, click **Save** to save the configuration
11. Next, you need to authorize the configuration. Click **Authorize**. You will be taken to the URL that you specified in the OAuth endpoint authorization URL field, where you will be prompted to log in
12. After you've successfully logged in, you'll be asked to give access to the Flow Builder application. **Confirm** this access, then you will be redirected back to the Integrations page to complete set up
13. If your application has been successfully authorized, you'll see a banner reading "All set! Your authorization is complete!". Click **Save and finish**. Now, when you go to Flow Builder, you'll be able to use this integration! 🎉

&#x20;

&#x20;

## Step two: Using the integration in Flow Builder

You can use the generic OAuth integration in the **Fetch variables** step and the **HTTP request** step in Flow Builder.

To use OAuth2 integration in one of these steps, go to the step's settings, and select your integration from the **OAuth integration** dropdown menu.&#x20;

**NOTE:** Only authorized integrations will be listed here. Integrations that have been created but not authorized are 'incomplete' and will not be listed here, as they cannot be used.

&#x20;

### Use case: Teamleader

Let's take a look at how we would set up a generic OAuth Integration for Teamleader. We want to fetch a contact's last name using the Teamleader contact ID in Flow Builder. Follow these steps to set this up:

1. Go to the [Integrations page](https://dashboard.messagebird.com/en-us/integrations/) in your [MessageBird Dashboard](https://dashboard.messagebird.com/)
2. Under OAuth, click **Add integration**. A form will appear with fields that you can complete
3. In the **Name** field, write '"teamleader" so that the integration is easy to find later
4. Now, we need to find the **Client ID** and the **Client secret** by creating an integration in Teamleader. Start by going to the [Teamleader Marketplace](https://marketplace.teamleader.eu/nl/en/build/integrations)&#x20;
5. Click **Create new integration** and enter a name, such as "flows"
6. Once you've created the integration, you'll be able to see the **Client ID** and the **Client secret**, as well as an input field for valid redirect URLs. Leave this empty for now, as we will come back to it in Step 12&#x20;

   <figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-e0d403f46add7716437e40f2af8e5b10f03d71d7%2FteamleaderClientID.png?alt=media" alt=""><figcaption></figcaption></figure>
7. Copy the **Client ID** and **Client secret** from Teamleader, and paste them into their respective fields in the OAuth integration form back in your MessageBird Dashboard. Don't close the page yet! There are still a few more things we need to do
8. In the **OAuth** **scopes** field, we'll need to enter a **scope**, which will allow us to fetch contact information from Teamleader. This scope is called 'contacts', so enter **contacts** into the scopes field. To choose the contacts scope from Teamleader, we'll also need to select the **contacts** checkbox in OAuth scopes, as shown in the image below

   <figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-08b2b6e9575c66c00ce8d118fa948042b843659f%2Fteamleader_scopes.png?alt=media" alt=""><figcaption></figcaption></figure>
9. Next, we'll need to fill in the **OAuth endpoint authorization URL** and **OAuth endpoint authorization token** fields in the OAuth integration form. To get these values, refer to the [Teamleader API documentation](https://developer.teamleader.eu/)&#x20;
10. Enter this URL in the **OAuth endpoint authorization URL** field: <https://app.teamleader.eu/oauth2/authorize>
11. Enter this URL in the **OAuth endpoint authorization token** field: <https://app.teamleader.eu/oauth2/access_token>&#x20;
12. You’ll see that the **User authorization callback URL field** is already filled for you. Copy this URL and paste it into the **Valid redirect URLs** field in the Teamleader marketplace integration page that we left empty in Step 6
13. Click **Save changes** in the Teamleader marketplace. The OAuth integration form should now look like this:<br>

    <figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-3b57d0d4a5c77ab908d7bbb51db505528d952b2d%2Funnamed.png?alt=media" alt=""><figcaption></figcaption></figure>
14. Click **Save** to save the integration
15. Click **Authorize**, and you'll be redirected to the Teamleader application. Login to Teamleader, grant access to Flow Builder, and you'll be redirected back to the Integrations page on the MessageBird Dashboard, where you'll see a banner that lets you know that your integration is complete! Click **Save and finish.** Congratulations, your integration is set up! 🎉

    <figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-eebe6c8922259f77dc6b29e33984338c4ba90829%2Fsave_and_finish.png?alt=media" alt=""><figcaption></figcaption></figure>
16. Now the OAuth integration is set up, we can use it to make authenticated requests from Flow Builder. Configure it as follows:<br>

    <figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-39379ff3251f7a99352e87a2a0b8664c86cb0fdf%2FScreenshot_2020-11-02_at_16.42.11.png?alt=media" alt=""><figcaption></figcaption></figure>
17. Go to Flow Builder and create or edit a flow with a **Fetch variables** step&#x20;
18. Add <https://api.teamleader.eu/contacts.info?id=>{{id}} into the **URL field**. For this to work, you will need to set up a flow to ask users to enter a Teamleader contact ID
19. Select the **Teamleader** integration from the **Select OAuth integration** drop-down menu
20. We can see in the Teamleader documentation that the response will have a **last\_name** field nestled under **data**. This can be used to reply to the user with the last name that is fetched from Teamleader. To start the flow, send a conversation message:

    <figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-3c40961ed12b67b029000e6b93dfc8abb23741f7%2FScreenshot_2020-11-02_at_16.53.09.png?alt=media" alt=""><figcaption></figcaption></figure>
21. As you can see from the screenshot above, FlowBuilder was able to make an authenticated request to Teamleader without requiring your credentials when invoking the flow! 🎉

&#x20;

### Use case: Zoho

For Zoho, you can extract the information that you need from the following articles:

* Go to <https://www.zoho.com/crm/developer/docs/api/v2/scopes.html> to get the proper scope definition. For each API that you access, you will need to have the proper scope. For example, if you want to access[ https://www.zoho.com/crm/developer/docs/api/v2/get-org-data.html](https://www.zoho.com/crm/developer/docs/api/v2/get-org-data.html) then you need to add the[ ZohoCRM.org](http://zohocrm.org/).ALL or[ ZohoCRM.org](http://zohocrm.org/).READ scopes
* Go to <https://www.zoho.com/crm/developer/docs/api/v2/register-client.html> to create the needed client on the Zoho side (a Server-based Applications application is needed)
* Go to <https://www.zoho.com/crm/developer/docs/api/v2/access-refresh.html> to get the link for the authorization token URL
* Go to <https://www.zoho.com/crm/developer/docs/api/v2/refresh.html> to get the link for the refresh URL

&#x20;

See how we've set up the Zoho app configuration. The redirect URL is the one copied from the Message Bird OAuth integration definition page.

&#x20;

<figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-409f45b3f1249ad8311e6fbd3bc532889b778848%2FScreen_Shot_2020-10-13_at_12.46.43_PM.png?alt=media" alt=""><figcaption></figcaption></figure>

&#x20;

### Troubleshooting Zoho OAuth integration

Zoho operates multiple data centers, that cannot communicate with each other, so if your organization is on[ zoho.eu](http://zoho.eu), you must replace all of the links in their documentation **.eu** links

This applies to both the OAuth configuration, OAuth endpoint authorization URL:[ https://accounts.zoho.com/oauth/v2/auth](https://accounts.zoho.com/oauth/v2/auth) becomes[ https://accounts.zoho.eu/oauth/v2/auth](https://accounts.zoho.eu/oauth/v2/auth) and to the actual links you are calling at runtime[ https://www.zohoapis.com/crm/v2/org](https://www.zohoapis.com/crm/v2/org) becomes[ https://www.zohoapis.eu/crm/v2/org](https://www.zohoapis.eu/crm/v2/org)