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.

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.

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)",
        }
    })

Secrets

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 the value for a 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)