When you’re connecting to an app, you need to authorize with it. A number of requests and responses are shared before the apps start sharing resources with each other. Using our platform, when an integration is created the user logs in to the third-party app and also authorizes Integry on their behalf. The endpoints that come in to play during the authorization process are the authorization endpoints. In this scenario, the endpoints are basically URLs that we need to send a request to perform the user authorization. 

We support a number of authorizations being used by apps these days. This article is a detailed guide to create the endpoints that are required while creating authorizations. You can create an authorization under the App Credentials tab in your Apps menu. The list of the authorization types is given below:

  • OAuth1.0
  • OAuth2.0
  • Basic with URL
  • Basic with API-Key
  • API-Key
  • API-Key and Secret
  • API Key with URL

To find out how each of these mechanisms work, read our detailed guide here.

When you add your app to Integry, you need to authorize it. By default, Integry adds the API-Key authentication to your app. The list of authorizations can be seen under the Authorizations heading in the App Credentials tab. The authorizations are easy to create. Click the Create Authorization button, select the authentication type from the drop-down menu. These authorizations require you to set up the following endpoints:

  • User Information Endpoint
  • Token Endpoint

Both these endpoints are of the Outgoing type, as in both cases we are making a call to an external API for user information and token information. User Information Endpoint is required by all auth types except Basic with API-Key. Similarly, the Access Token Endpoints are only required by OAuth and Basic auth type. These endpoints are explained in detail below.

User Information Endpoint

The User Information Endpoint is of Outgoing type. It handles user details when they log in to the third party app while creating an integration. This endpoint fetches the basic user information from the third-party app and displays in the widget field as shown below.

The user details are accessed by making an API call to the third party app. Let us say we want to configure a Basecamp account in our widget. From the  Basecamp API Docs, we know the following endpoint has to be called for authorization

GET https://launchpad.37signals.com/authorization.json

And the response is returned in the following format

{
  "expires_at": "2012-03-22T16:56:48-05:00",
  "identity": {
    "id": 9999999,
    "first_name": "Jason",
    "last_name": "Fried",
    "email_address": "jason@basecamp.com",
  },
  "accounts": [
    {
      "product": "bc3",
      "id": 99999999,
      "name": "Honcho Design",
      "href": "https://3.basecampapi.com/99999999",
      "app_href": "https://3.basecamp.com/99999999"
    },
    {
      "product": "bcx",
      "id": 88888888,
      "name": "Wayne Enterprises, Ltd.",
      "href": "https://basecamp.com/88888888/api/v1",
      "app_href": "https://basecamp.com/88888888"
    }
  ]
}

Our endpoint will have the following structure.

Request URL

Our URL will be the same as shown above and we will use the GET method. 

Response Template

The response we receive from the external API is passed on to the widget field. The user information like first name, last name, email ID or any other information is displayed in that field. So, once we receive the response we have to transform it using the response Twig object. Keeping in view Basecamp response format our template will look like this

{
"user_identity": "{{ response.identity.first_name }} {{ response.identity.last_name }} / {{ response.identity.email_address }}"
}

We output the user first name, last name and email address using Twig objects. The values are assigned to user_identity variable. It is very important that you use the same variable names while writing your template else your field will display nothing. 

Header

Header carries additional information that needs to be sent with the request or a response. The HTTP accepts the headers in the following format:

        Case-sensitive header name: Header Value

It is an optional field, as in some cases no headers are required. Depending on the requirement of your app, the header can be added. They vary from app to app. To add a header in your endpoint, click the Add Header button. Two fields will appear, one for the header name and the other for the header value as shown below

Depending on the headers that your request or response requires just fill them in. 

The first header in the image above takes the value of access token. The value of the access token received through the token endpoint incoming request can be read off of the query variable as shown above. The values are accessed by combing query with the property name like query.access_token. It is then used as a header for this endpoint. The headers depend on the API Documentation of an app.

The user information returned is different for different apps. The formats they use may vary from app to app. The example above is Basecamp specific.  

Access Token Endpoint

While we are dealing with OAuth1.0, OAuth2.0 or Basic auth type we have to work with access and refresh tokens. These tokens are explained, here

Once the user logs in, Basecamp sends an Authorization Code back to Integry. With the use of this code and other app credentials, we can request Access Token. To request this token we create Access Token Endpoint, without this token you cannot access the Basecamp resources. 

The Access Token Endpoint field appears only in OAuth1.0, OAuth2.0, and Basic auth types. This is Outgoing type endpoint ( as we are requesting data from another app).

URL Structure

From the Basecamp API Docs, we learn to request an access token following endpoint has to be called

POST https://launchpad.37signals.com/authorization/token?type=web_server&client_id=your-client-id&redirect_uri=your-redirect-uri&client_secret=your-client-secret&code=verification-code

Various apps support various formats for an access token request. In the example above, we can see the URL takes the Client ID, Redirect_URI, Client Secret and Authorization Code (Verification Code). 

Client ID: The client ID of the app registered with us.

Client Secret: The client secret of the app registered with us.

Redirect URI: The URL where the user is directed once the user logs in.

Authorization Code: The code we received when the user logged in, to authenticate us. 

The URL of the endpoint will look like this

POST https://launchpad.37signals.com/authorization/token?type=web_server&client_id={{requestBody.client_id}}&redirect_uri={{requestBody.redirect_uri|raw}}&client_secret={{requestBody.client_secret}}&code={{requestBody.code}}

As all the information is passed in the URL so our response template will be empty. All the information is available in the requestBody object and can be accessed as shown in the URL above. This example is Basecamp specific. There are apps that take these values as a part of the request payload. These values can be read off the requestBody object using Twig.

Response Template

The response returned contains the access and refresh tokens. We need to save them for later use. So the response template will output the values and store them as shown below

{
   "access_token": "{{ response.access_token }}",
   "refresh_token": "{{ response.refresh_token }}"
}

It is very important that you use the same variable names in your response template, otherwise, you will not be authorized. The template reads the values of tokens off response object using Twig. 

Let us consider another example, where the values of client ID, authorization code etc. are passed in the request template. We will consider GoTo Meeting for this example. It uses OAuth2.0 for authentication. The API Docs, tell us the authorization request is sent to the following endpoint

POST https://api.getgo.com/oauth/v2/token

Request Template

The request body will contain the information like client ID, authorization code etc. 

The data is available through the requestBody object. The template will look like as shown below


{
   "redirect_uri": "{{ requestBody.redirect_uri }}",
   "code": "{{ requestBody.code }}",
   {
      %
      if requestBody.grant_type is defined %
   }
   "grant_type": "{{ requestBody.grant_type }}" {
      %
      if requestBody.grant_type == 'refresh_token'
      and requestBody.refresh_token is defined %
   },
   "refresh_token": "{{ requestBody.refresh_token }}" {
      % endif %
   } {
      %
      else %
   }
   "grant_type": "authorization_code" {
      % endif %
   }

}

There are a few conditional statements implemented in the code above. These statements check whether the request is being made for the access token or refresh token.

Response Template

The response template will save the tokens received using Twig. It will look like as shown below

{
   "access_token": "{{ response.access_token }}",
   "refresh_token": "{{ response.refresh_token }}",
   "extras": {
   "organizer_key": "{{ response.organizer_key }}"
}

Header Details

Header carries additional information that needs to be sent with the request or a response. The HTTP accepts the headers in the following format:

Case-sensitive header name: Header Value

It is an optional field, as in some cases no headers are required. Depending on the requirement of your app, the header can be added. They vary from app to app. To add a header in your endpoint, click the Add Header button. Two fields will appear, one for the header name and the other for the header value as shown below

Depending on the headers that your request or response requires just fill them in. 

The first header in the image above takes the value of access token. The value of the access token received through the token endpoint can be read off of the query variable as shown above.   

The user information returned is different for different apps. The formats they use may vary from app to app. The example above is Basecamp specific. 

Did this answer your question?