Integrations

The integrations API lets you build plugins integrating third-party API services into Qatium. The integrations API allows fetching HTTP requests through Qatium’s gateway, and managing user secrets for authentication and other uses.

The integrations.secrets API lets you store and retrieve secret data for users and networks. Storing these secrets allows users to configure all required credentials for API integrations, such as usernames, passwords, API keys, API URLs, etc.

Secrets are stored safely in Qatium’s infrastructure, ensuring privacy and confidentiality.

Secrets

Secrets are stored in two levels:

1. User + Network level

This level allows plugin developers to ask for user specific secrets for each instance of the plugin.

This means that the secret will be only available for that specific User in an specific Network.

Use this level when you want specific user credentials or secrets, like login credentials, or custom configurations depending on the user and network.

The API secrets.set configures the secret at this level.

2. Plugin Level

This level allows plugin developers to set secrets to all the plugin instances for all the users.

This means that the secret will be used by all the users.

Use this level when you want to hide a secret from the user but still need it to perform an integration.

An example may be an API_URL or API_TOKEN secret which you need to use for your plugin but you don’t want to share with the plugin code and neither ask the user to provide it.

As for now, in order to configure this kind of secrets send an email to support@qatium.com.

Level preference

In the scenario where you may want to store a plugin level secret but also give the user to provide a secret, the user one will have preference.

Example: A plugin uses an API_URL secret. The plugin developer sets a default API_URL for all users. However, a specific user in a specific network can override this default by setting their own API_URL. In this case, the user’s API_URL will be used for that user in that network, while other users will use the plugin developer’s default API_URL.

secrets.get()

Returns a secret value by name.

Resolves to no-op when running in developer mode unless your developer account is approved by Qatium to do third-party API integrations.

get(key: string): Promise<string>

async def get(key: str) -> str:

Parameters

key: Secret name.

Returns

A promise that resolves after the secret value is retrieved from Qatium’s infrastructure. If the secret does not exist or an error occurs, an empty string ("") will be returned.

Example

TypeScript
Python

async run() {
  // Retrieve username
  const username = await sdk.integrations.secrets.get("USERNAME");
}

async def run():
    # Retrieve username
    username = await sdk.integrations.secrets.get("USERNAME")

secrets.has()

Returns whether a secret exists by name.

Resolves to no-op when running in developer mode unless your developer account is approved by Qatium to do third-party API integrations.

Method signature

TypeScript
Python

has(key: string): Promise<boolean>

async def has(key: str) -> bool:

Parameters

key: Secret name.

Returns

A promise that resolves after verifying whether the secret exists in Qatium’s infrastructure. If the secret does not exist or an error occurs, false will be returned.

Example

TypeScript
Python

async run() {
  // Check if the username is set
  const hasUsername = await sdk.integrations.secrets.has("USERNAME");
}

async def run():
    # Check if the username is set
    has_username = await sdk.integrations.secrets.has("USERNAME")

secrets.set()

Sets a user level secret by key.

Resolves to no-op when running in developer mode unless your developer account is approved by Qatium to do third-party API integrations.

Method signature

TypeScript
Python

set(key: string, value: string): Promise<Success | Failure>

async def set(key: str, value: str) -> Union[Success, Failure]:

Parameters

key: Secret name.
value: Secret value.

Returns

A promise that resolves after the secret value has been updated. The returned value informs whether the operation has succeeded or failed.

Example

TypeScript
Python

async onMessage<MessageFromUI>({ username }) {
  // Set the username
  const result = await sdk.integrations.secrets.set("USERNAME", username);

  if (result.status === "success") {
    // All good!
  } else {
    // Something went wrong
    console.log("error: ", result.error);
  }
}

async def onMessage(message):
    username = message['username']

    # Set the username
    result = await sdk.integrations.secrets.set("USERNAME", username)

    if result.status == "success":
        # All good!
        pass
    else:
        # Something went wrong
        print("error:", result.error)

Fetch API

fetch()

Performs an HTTP fetch proxied through Qatium’s API integration gateway. Behaves in the same way as the built-in fetch() method. Check the fetch method documentation to know more.

Resolves to no-op when running in developer mode unless your developer account is approved by Qatium to do third-party API integrations.

Using secrets

The fetch API works in combination with the Secrets API to provide a secure way of integrating with third-party APIs. You can use the stored secrets in the API requests using the format $(secret:SECRET_KEY) where SECRET_KEY is the name of the stored secret.

Both secret levels will be used.

You can find an example of how to combine secrets in API integrations in this example.

Parameters

input: URL as a string, URL Object, or Request object.
init: (Optional) HTTP request options.

Returns

A promise resolving with the HTTP response.

Example

Perform a request to a third-party API:

TypeScript
Python

async init() {
  const response = await sdk.integrations.fetch("https://example.com");
  const result = await response.text();
}

async def init():
    response = await sdk.integrations.fetch("https://example.com")
    result = await response.text()

Perform a request to a third-party API using secrets:

TypeScript
Python

async onMessage<MessageFromUI>({ username, password }) {
  // Set the username and password
  await sdk.integrations.secrets.set("USERNAME", username);
  await sdk.integrations.secrets.set("PASSWORD", password);

  const response = await sdk.integrations.fetch("https://my-api.com", {
    body: {
      username: "$(secret:USERNAME)",
      password: "$(secret:PASSWORD)",
    }
  });
}

async def onMessage(message):
    username = message['username']
    password = message['password']

    # Set the username and password
    await sdk.integrations.secrets.set("USERNAME", username)
    await sdk.integrations.secrets.set("PASSWORD", password)

    response = await sdk.integrations.fetch("https://my-api.com", {
        'body': {
            'username': "$(secret:USERNAME)",
            'password': "$(secret:PASSWORD)",
        }
    })