Using external APIs in Custom Actions

If you need to do simple calls to an external API from a BRYTER application, you can do this by using a custom action. In order for your custom action to securely communicate with an API we have created API connections.

API Connections enables you as a developer to write custom actions which call external service that requires authentication. The credentials are stored safely and can not be seen by anyone. We will now walk you through how to enable connections for a custom action.

Create an API connection

In order to configure a custom action with connections we need to create the API connection.

HTTP/1.1
POST /api/application/<application-id>/connections
Accept: application/json
Content-Type: application/json
Authorization: Bearer <actions-api-key>

{
	"name": "Acme Inc Inventory API",
	"type": "API_KEY"
}

The name of a connection needs to be something that makes sense to you, while the type currently only supports API_KEY. Other authentication methods will be added in the future.

The response will contain the connection id (the id attribute in the JSON below) to use when creating a custom action.

{
	"id": "tFBs_jvzQTCnWlrUzz9tFg",
	"type": "API_KEY",
	"name": "Acme Inc Inventory API",
	"applicationId": "{application id}",
	"createdAt": "2023-06-01T11:45:14.459434152Z",
	"updatedAt": "2023-06-01T11:45:14.459434152Z"
}

Create a custom action with a connection

In order for a custom action to have access to the authentication data, we need to configure it to have a connection. It requires:

The ID your retrieved from the connection created
An Alias that you define to refer to that connection

{
  "key": "word-count",
  "name": "Word count",
  "description": "Counts words in the input text",
	"developerEmail": "mail@example.com",
  "parameters": [
    {
      "name": "Text to count",
      "type": "text",
      "description": "The text to count"
    }
  ],
	"connections": [{
		"id": "tFBs_jvzQTCnWlrUzz9tFg",
		"alias": "AcmeIncKey"
	}], 
  "result": {
    "type": "number",
    "description": "The number of words in the text"
  }
}

The connections attribute contains a reference to the connection id created earlier and it also needs a reference to an alias. The alias is what you use to access the connection information in your custom action code:

connections['AcmeIncKey'].token

When a custom action is configured to use connections there is an additional argument sent to your custom action main function. In order to get the right connection, we use the alias specified in earlier.

async function main (somePatameter: Number, connections): Promise<string> {
	const response = await fetch('https://acme.inc/api/inventory', {
		Headers: {
			Authorization: `Bearer ${connections['MyAlias'].token}`
		}
	}
	const result = await response.json()
	return result
}

The connections objects has a token property which contains the actual secret

Configuring your connection

With the custom action configured to use an external API there is one more thing we need to do, which is to configure the connection with the actual secrets required for authentication.

In the BRYTER application you navigate to your application, navigate to settings and then select the Connect option in tab menu

This screen shows you all custom actions available for the application.

Selecting an item in the list you will see the detailed information about your custom action. This information includes all the environments available where you configure the secret for you API connection.

Click the “Configure” link and a dialog appears where you can enter the secret information.

Voila 🎉 you can now safely and securely talk to HTTP APIs in your custom action.