API key is an authorization type known for its simplicity. API-key is the name given to a secret token that is submitted to a web service along with a request. The key identifies the user in an app and performs API request on behalf of that user. For more details about API-key and how it works, read our guide.

We support API-Key, and two of its other variations which are API-Key with Secret and API-Key with URL for authorization. All these come under the same umbrella. The basic difference is that API-Key with Secret uses a combination of key and secret to identify the user whereas the API-Key with URL uses a combination of key and a custom URL. All these authorization types are created in the same way.  

How to create API-Key authorization?

This is a detailed guide on how to create API-Key authorization types through Integry. When you create your app, Integry configures API-Key by default with your app. If you want to create another authorization type, you can delete this one. The authorization is created under the App Credentials tab in your app menu. Authorizations display all authorization types configured with your app. So let’s walk through the entire authorization creation process. 

Click the Create Authorization button. A drop-down menu will appear as shown below. The procedure is the same for these authorization types. Select the API-Key with Secret / API-Key with URL from the list.

We need to add an endpoint. The field that appears below takes the User Information Endpoint (UIE). UIE sends the authorization request and returns the details of the logged in user. To create a new user information endpoint, select Create a new endpoint option from the drop-down menu. Read, how to create a new user information endpoint.

How are they different?

When you create an app that uses API-Key with URL every user of that app is assigned a unique URL where they can access the app. When you create actions or triggers, you need to provide this URL that changes for every user. Let us take the example of an app that uses API-Key with URL, Quaderno.

We want to an action "Create a Contact" in your app Quaderno. We need to execute the endpoint that will create a contact in Quaderno on Integry’s behalf. The URL for the endpoint is different for every user in this case. Before we do that just a few things.

How to access the Custom Authorization URL

When an app uses API-Key with URL authorization, the custom URL entered by the user when they authenticate is available to your actions/triggers endpoints like authorization.token.extras.base_uri. This is a standard Integry syntax. We use Twig templating language and provide the value of the URL as a JSON object. It is available for all apps using API-Key with URL. As we want to create a contact and from the documentation, we know we need to provide the custom user URL. So our action endpoint URL will be 

POST {{authorization.token.extras.base_uri | raw}}/rest/api/2/issue/

“{{ }}” means that the value inside the authorization.token.extras.base_uri is outputted here. The rest of the URL part is appended at the end as specified in the documentation. 

| raw is a filter applied to the URL. We want to get the raw value of the URL, so we apply this filter to prevent escaping.

The method to create API-Key, API-Key with Secret and API-Key with URL authorization types is the same. So how are they different? 

The user can view all integrations available in the Integry widget. When a user creates an integration, they are asked to authorize themselves to the third-party app and add their account as shown below

In the figure above, the user is asked to add People HR account.

Different apps use different authentication methods. We will discuss three different scenarios where the user authenticates with apps using the following authorization types: 

  • API-Key
  • API-Key with Secret 
  • API-Key with URL

Authorizing with API-Key

When a user adds a third-party app account that uses API-Key, they are directed to the authorization screen as shown below

The form shown above takes the name of authorization and the value of API-Key. If your app uses API-Key, your users can copy and paste that here in the API-Key field. Once provided, the user is authenticated. 

Authorizing with API-Key with Secret

When a user adds a third-party app account that uses API-Key with Secret, they are directed to the authorization screen as shown below

The form shown above takes the name of authorization, the value of API-Key and the API Secret. In this scenario, the user in addition to API-Key needs to provide API Secret as well. If your app uses API-Key with Secret the user can copy and paste them here. Once provided, the user is authenticated. 

Authorizing with API-Key with URL

When a user adds a third-party app account that uses API-Key with URL, they are directed to the authorization screen as shown below

The form shown above takes the name of authorization, the value of API-Key and Custom URL. Here, in addition to API-Key, the user also needs to provide a custom authentication URL. If your app uses API-Key with URL, your users can copy and paste their values here. Once provided, the user is authenticated. 

So, by the end of this article, we hope you are now familiar with API-Key, how it works and also its different variations. 

Did this answer your question?