Create API connections

API connections let you define reusable endpoints and settings, such as authentication, timeouts, and encryption, which you can use across your API tests. This keeps your tests consistent and save time on maintenance.

Create a new connection

To create a new connection, follow these steps:

  1. Go to Configurations > API connections and select Create connection.

  2. Enter your connection details:

    Property

    Description

    Name

    Enter a unique name for the connection.

    Type

    Specify this property to use a connection technology other than the default HTTP. For instance, to send or receive messages via message broker or to connect to a file system. Valid values are ActiveMQ, ActiveMQ Artemis, Amazon SNS, Amazon SQS, File, IBM MQ, Kafka, MLLP, MSMQ, Oracle WebLogic, Rabbit MQ, SAP RFC, Tibco EMS, and WebSocket.

    Endpoint

    Specify the endpoint to which you want to send messages. This can be a URI, a port, or an IP address.

  3. Select Create.

Set up connection details

After you create a connection, you can configure additional settings. Select a connection from the list and use the properties panel on the right to adjust the following:

The connection type defines the technology your connection uses to communicate with the API endpoint.

Select a connection type for your API: HTTP for REST APIs, a message broker like ActiveMQ or IBM MQ to send or receive messages via queues and topics, or File to connect to a folder.

The following types are available:

An ActiveMQ connection sends and receives messages from ActiveMQ queues or topics.

Configure your ActiveMQ connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select ActiveMQ.

Queue/Topic Name

Enter the name of the ActiveMQ queue or topic you want to connect to.

Host

Specify the name or IP address of the ActiveMQ server host.

Port

Enter the port number for the server.

Type

Select Queue for a one-to-one messaging pattern, or Topic for one-to-many messaging.

Message Type

Select JmsTextMessage for text-only messages, or JmsBytesMessage for binary messages.

Peeking

Enable to retrieve messages from queues without consuming them.

Secure connection

Enable to establish a connection with a secure protocol.

Security Protocol

Select a security protocol to establish secure communications by encrypting the transmitted data. The Default value uses the highest security protocol version the server supports.

Username and Password

If authentication is required, enter your credentials.

Certificate and Passphrase

If client certificate authentication is required, enter the certificate and passphrase.

Optionally, configure XML and web service security.

An ActiveMQ Artemis connection sends and receives messages from ActiveMQ Artemis queues.

Configure your ActiveMQ Artemis connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select ActiveMQ Artemis.

Queue Name

Enter the name of the ActiveMQ Artemis queue you want to connect to.

Host

Specify the name or IP address of the ActiveMQ Artemis server host.

Port

Enter the port number for the server.

Username and Password

In the Authentication section, enter your credentials if authentication is required.

An Amazon SNS connection sends notifications to SNS topics.

To use an Amazon SNS connection, you need an AWS account, an access key in Identity and Access Management (IAM), and an SNS topic.

Configure your Amazon SNS connection with the following fields:

Field

Description

Type

Select Amazon SNS.

ARN

Copy the Amazon Resource Name (ARN) of your SNS topic from the AWS console. The system then automatically populates the following fields:

  • Topic: The name of the topic you want to send a message to.

  • Account: The AWS account ID number.

  • Partition: The AWS environment in which the SNS topic exists. The default value is aws. If your SQS queue is located in a standard AWS region, leave the partition set to aws.

You can also modify the values manually. Your entries update the ARN value.

Access Key and Secret Key

In the Authentication section, enter credentials for your AWS account.

Region

Select a region from the dropdown menu. The default value is US East (Ohio). Your selection updates the ARN value.

Session Token

Optionally, enter if you have temporary credentials.

An Amazon SQS connection sends and receives messages from SQS queues.

To use an Amazon SQS connection, you need an AWS account, an access key in Identity and Access Management (IAM), and a standard SQS queue.

Configure your Amazon SQS connection with the following fields:

Field

Description

Type

Select Amazon SQS.

ARN

Copy the Amazon Resource Name (ARN) of your selected SQS queue from the AWS console in the Details tab. The system then automatically populates the following fields:

  • Queue name: The name of the queue you want to send a message to.

  • Account: The AWS account ID number.

  • Partition: The AWS environment in which the SNS topic exists. The default value is aws. If your SQS queue is located in a standard AWS region, leave the partition set to aws.

  • Peeking: Select this option in case you want to retrieve messages from queues without consuming them.

You can also modify the values manually. Your entries update the ARN value.

Access Key and Secret Key

In the Authentication section, enter credentials for your AWS account.

Region

Select a region from the dropdown menu. The default value is US East (Ohio). Your selection updates the ARN value.

Session Token

Optionally, enter if you have temporary credentials.

A file connection reads from and writes to files. You can load test data or save results to local or network file systems.

Configure your file connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select File.

Endpoint

Enter a full file path. The endpoint has to start with file://.

An HTTP or HTTPS connection sends and receives messages with REST APIs and web services. HTTPS provides encrypted communication.

Configure your HTTP/HTTPS connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select HTTP/HTTPS.

Endpoint

Enter the endpoint URL, for example, https://example.com/api.

Response timeout

Specify a response timeout. The default value is 60000 milliseconds.

Proxy

If you use a proxy, enter the proxy server address in the format http://address:port and the proxy username and password.

Authentication

If authentication is required, configure your authentication type.

Optionally, configure XML and web service security.

An IBM MQ connection sends and receives messages from IBM MQ queues or topics.

To use an IBM MQ connection, you need to have IBM MQ Client Library 9.1.0.4 or later. If you use an earlier version, create a redirect as described in this Tricentis Knowledge Base article (opens in new tab).

Configure your IBM MQ connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select IBM MQ.

Queue/Topic Name

Enter the name of the queue or topic you want to connect to. To use an alternative queue manager, use the format queue://my-alternative-qmgr/my-queue in the Queue/Topic Name field.

Host

Specify the name or IP address of the IBM MQ server host.

Port

Enter the port number for the server.

Channel

Specify the channel that you want to use to transfer messages.

Manager

Enter the manager that manages the messages in the queue.

Type

Select Queue for a one-to-one messaging pattern, or Topic for one-to-many messaging.

Message Type

Select JmsTextMessage for text-only messages, or JmsBytesMessage for binary messages.

Jms Support

Select WmqWithJMS if the client type is JMS, or WmqNative for native IBM MQ.

Peeking

Enable it to retrieve messages from topics or queues without consuming them.

Cipher Spec

Specify a combination of encryption algorithm and message authentication code algorithm, such as ECDHE_ECDSA_AES_128_CBC_SHA256, to enable encrypted communication (SSL/TLS). We recommend that you use this method to select a spec. For detailed information, see the IBM MQ documentation (opens in new tab).

Cipher Suite

Specify a suite of cryptographic algorithms, such as SSL_RSA_WITH_RC4_128_MD5, as an alternative way to select a spec. For detailed information, see the IBM MQ documentation (opens in new tab).

Peer Name

Specify a string that contains the peer name. For detailed information, see the IBM MQ documentation with general information and an example of a peer name.

Key Repository

Optionally, set the Windows key store you want to use with one of these options:

  • *SYSTEM: Accesses the local computer account to retrieve the certificates.

  • *USER: Accesses the current user's certificate store to retrieve the client certificates.

    Place client certificates in the user's or computer's My Certificate store. Place all server (CA) certificates in the root directory of the certificate store. For detailed information, see the IBM MQ documentation (opens in new tab).

Certificate Stores

Specify a comma-separated list that contains one or more URLs of the certificate store servers. For detailed information, see the IBM MQ documentation (opens in new tab).

Username and Password

If authentication is required, enter your credentials.

Optionally, configure XML and web service security.

An Apache Kafka connection sends and receives messages from Kafka topics.

Configure your Kafka connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select Kafka.

Topic

Enter the name of the topic you want to connect to.

Host

Specify the name or IP address of the Kafka server host.

Port

Enter the port number for the server.

GroupId

Specify the group ID of the consumer group. This is the name of the group of consumers that subscribed to this topic.

Partition

Enter the number of the partition that stores the records (messages). Kafka topics are split into multiple partitions which allows for a distribution of large amounts of data on one or more servers. Each partition has a number such as 0 or 5.

ClientPropertiesFile

Specify the path to the file that contains specific Kafka connection settings. To see the available properties, check the Kafka documentation (opens in new tab).

Peeking

Enable to retrieve records from a partition without committing. You can read any record regardless of its position in the partition without affecting the offset. The offset defines the position of a record and indicates which records have been consumed and which unread record the API engine should pull next.

KeyType

Specify the message key type with one of the following options:

  • Ignore: Sets the message key to null and serialize only the message value.

  • None: Doesn't serialize either the Kafka message key or the message value.

  • Integer: Uses an integer value as the message key and serializes the key as an integer.

  • String: Uses a string value as the message key and serializes the key as a string.

Treat warning as error

Select to show warnings as errors that occur during execution.

Username and Password

If authentication is required, choose one of two options: authenticate with Username and Password or via SSL.

Certificate

If you choose SSL, specify your certificate file in .pem.

Passphrase

If you choose SSL, insert the passphrase for your private key.

Private Key

If you choose SSL, specify the path to your private key in .pem.

CA Certificate

If you choose SSL, specify the root CA Certificate in .pem for verifying the Kafka broker's certificate.

Client Property File Secrets

Define to establish a secure and authenticated connection between your Kafka client and the Kafka broker. These secrets store sensitive information.

Schema Type

Optionally, add Avro schema-based serialization for Kafka messages to define the data schema for a record's value. Select Avro and add a Schema Registry Url and a Schema that defines the data structure in a JSON format. This schema describes the fields allowed in the value, along with their data types. For detailed information on Avro schema, see the Apache Avro documentation (opens in new tab).

Optionally, configure XML and web service security.

Avro schema serialization format support

Avro is a data serialization format that converts structured data into a compact binary format. When you use Avro with Kafka, you define a schema to ensure consistent message formatting between producers and consumers. Kafka connections support the following Avro schema types:

  • Array

  • Boolean

  • Double

  • Enum

  • Float

  • Int

  • Logical: Date, Time (millisecond), Time (microsecond), Timestamp (millisecond), Timestamp (microsecond), Local timestamp (millisecond), Local timestamp (microsecond), UUID

  • Long

  • Null

  • Record

  • String

  • Union

API Engine doesn't support the default value for array types in an Avro schema. Specifically, it doesn't allow the value "default": [] for fields with "type": "array".

An MLLP connection sends Health Level-7 (HL7) messages.

Configure your MLLP connection with the following fields:

Field

Description

Type

Select MLLP.

Endpoint

Enter host name or host IP address and port separated by a colon. For example: 10.100.12.34:11000.

An MSMQ connection sends and receives messages from MSMQ queues.

Configure your MSMQ connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select MSMQ.

Path

Specify the path to the queue. Use the name of the machine that stores the queue messages and the name of the queue. For public queues, specify the path in this format: machine\queue. For private queues, specify the path in this format: machine\private$\queue.

Peeking

Enable to retrieve messages from queues without consuming them.

Username and Password

If authentication is required, enter your credentials.

Optionally, configure XML and web service security.

An Oracle WebLogic connection sends and receives messages from Oracle WebLogic queues or topics.

To use an Oracle WebLogic connection, you need the WebLogic JMS .NET client libraries.

Configure your Oracle WebLogic connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select Oracle WebLogic.

Queue/Topic Name

Enter the name of the queue or topic you want to connect to.

Connection Factory

Enter the name of the connection factory. The connection factory enables the JMS client to create a JMS connection.

Host

Specify the name or IP address of the Oracle WebLogic server host.

Port

Enter the port number for the server.

Type

Select Queue for a one-to-one messaging pattern, or Topic for one-to-many messaging.

Message Type

Select JmsTextMessage for text-only messages, or JmsBytesMessage for binary messages.

Peeking

Enable to retrieve messages from topics or queues without consuming them.

Username and Password

If authentication is required, enter your credentials.

Optionally, configure XML and web service security.

A RabbitMQ connection sends and receives messages from RabbitMQ queues or topics.

Configure your Rabbit MQ connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select RabbitMQ.

Queue/Topic Name

Enter the name of the queue or topic you want to connect to.

Routing Key

Enter the routing key that specifies which queue receives a message.

Exchange

Specify the name of the exchange that receives your messages and routes them to queues. If you don't specify one, the system uses the default exchange.

Host

Specify the name or IP address of the Rabbit MQ server host.

Port

Enter the port number for the server.

Virtual Host

Optionally, enter the name of the virtual host you want to use.

Type

Select Queue for a one-to-one messaging pattern, or Topic for one-to-many messaging.

Peeking

Enable to retrieve messages from topics or queues without consuming them.

Secure connection

Enable to establish a connection with a secure protocol.

Verify Server Certificate

Enable if you want the client to verify the server certificate.

Username and Password

If authentication is required, enter your credentials.

Certificate and Passphrase

If client certificate authentication is required, enter the certificate and passphrase.

Optionally, configure XML and web service security.

An SAP RFC connection calls SAP functions remotely and exchanges data with SAP systems.

To use an SAP RFC connection, you need to add SAP .NET Connector 3.1 libraries:

  1. Download SAP .NET Connector 3.1 for 64-bit system types from the SAP Service Marketplace (opens in new tab).

  2. Go to the installation directory of the SAP .NET Connector and copy the following libraries from the 64-bit version to C:\Program Files (x86)\TRICENTIS\Tosca Testsuite\TBox and %COMMANDER_HOME%:

    • cpc4n.dll

    • ijwhost.dll

    • Microsoft.Win32.Registry.dll

    • sapnco.dll

    • sapnco_utils.dll

    • System.Configuration.ConfigurationManager.dll

Configure your SAP RFC connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select SAP RFC.

SAP Server

Enter the IP address of the SAP server.

SAP Server Port

Specify the SAP server port. To find the port, check the SAP gateway line entry sapgw00 3300/tcp in C:\Windows\System32\drivers\etc\services. The port consists of the service sapgw00 value plus the instance number. For example, if sapgw00 is 3300 and the instance number is 60, the port number is 3360.

Gateway and Gateway Port

Enter the gateway and gateway port required to connect. If unavailable, use the SAP Server and SAP Server Port values instead.

Client ID

Enter a three-digit SAP client ID. If you don't enter one, the API engine uses the default client ID 000.

SAP Router String

If you cannot establish a connection using the SAP Server, Server Port, Gateway, and Gateway Port values, use the SAP Router String as an alternative.

Username and Password

If authentication is required, enter your credentials.

A Tibco EMS connection sends and receives messages from Tibco EMS queues or topics.

To use a Tibco EMS connection, you need the Tibco EMS client library.

Configure your Tibco EMS connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select Tibco EMS.

Queue/Topic Name

Enter the name of the queue or topic you want to connect to.

Host

Specify the name or IP address of the Tibco EMS server host.

Port

Enter the port number for the server.

Type

Select Queue for a one-to-one messaging pattern, or Topic for one-to-many messaging.

Message Type

Select JmsTextMessage for text-only messages, or JmsBytesMessage for binary messages.

Peeking

Enable to retrieve messages from topics or queues without consuming them.

Secure connection

Enable to establish a connection with a secure protocol.

Target Host

If you use a secure connection, enter the name of the server as specified in the server certificate.

Username and Password

If authentication is required, enter your credentials.

Optionally, configure XML and web service security.

A WebSocket connection sends and receives messages in real time. WebSocket provides persistent, bidirectional communication.

Configure your WebSocket connection with the following fields:

Field

Description

Name

Specify a name for your connection.

Type

Select WebSocket.

Endpoint

Enter an endpoint URL. Your endpoint has to start with ws:// or wss://.

Response timeout

Specify a response timeout. The default value is 60000 milliseconds.

Username and Password

If authentication is required, enter your credentials.

Specify the authentication method for your connection. Select an authentication type and enter the required details.

Select None if the endpoint doesn't require authentication. If you want to provide a custom authorization header in your API message, set authentication to None and add the header manually.

Send a username and password with your request.

Configure the following properties:

Property

Description

Username

Enter your username.

Password

Enter your password.

Pre-authenticate

Enable this option to send authentication details with your first request. Without pre-authentication, the first request doesn't include credentials, and the server returns a challenge before you can authenticate.

Authenticate requests to Amazon Web Services (AWS) with your access key and secret key.

Configure the following properties:

Property

Description

Access Key

Enter your AWS access key ID.

Secret Key

Enter your AWS secret access key.

Session Token

Optional. Enter your session token if you use temporary credentials.

Service Name

Enter the name of the AWS service you want to authenticate with. For example, sqs or s3.

Region

Select the AWS region of the service endpoint.

Use a certificate file to verify your identity.

Configure the following properties:

Property

Description

Certificate

Enter the file path to your client certificate.

Passphrase

Enter your passphrase if your certificate requires one.

Securely transmit credentials as a hash, so the server never receives your password in plain text.

Configure the following properties:

Property

Description

Username

Enter your username.

Password

Enter your password.

Use certificates stored in a Java Keystore file to authenticate your connection.

Configure the following properties:

Property

Description

Keystore

Enter the file path to your .jks file.

Keystore Password

Enter the password if the keystore requires one.

Certificate

Select the certificate from your keystore.

Certificate Password

Enter the password if the certificate requires one.

Authenticate with Kerberos tickets or Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) for Single Sign-On (SSO) in environments that support Kerberos.

Configure the following properties:

Property

Description

Username

Enter your username.

Password

Enter your password.

Domain

Specify the domain of the authentication service.

Authenticate with the NT LAN Manager (NTLM) challenge-response protocol, common in Windows environments. NTLM verifies user identity without transmitting the password over the network.

Configure the following properties:

Property

Description

Username

Enter your Windows username.

Password

Enter your Windows password.

Domain

Specify the Windows domain against which to authenticate.

Use token-based authentication. Select a grant type that matches your authorization flow and enter the required details.

Configure the following properties:

Property

Description

Grant Type

Select how the application receives the access token. The following grant types are available:

  • Authorization Code

  • Authorization Code (PKCE)

  • Implicit

  • Password

  • Client Credentials

Authorization Endpoint

Enter the authorization server URI.

Token Endpoint

Enter the token server URI.

Redirect URI

Optional. Enter the redirect URI.

Client ID

Enter the client identifier issued by the authorization server when you registered your application.

Client Secret

Enter the client secret to authenticate the identity of your application.

Username

Enter your username. Required for the Password grant type.

Password

Enter your password. Required for the Password grant type.

Scope

Optional. Specify the scope of permissions the application requests. Enter one or more space-separated values, for example openid profile.

Send Client Secret

Specify how Tosca Cloud sends the client secret during authentication.

  • As Header sends it as an authorization header.

  • As Content sends it as a parameter in the request payload.

  • Default sends it in both.

Send Origin header

Specify whether Tosca Cloud should send the CORS (origin) header. The Default option uses the same behavior as in earlier versions.

Code Challenge Method

Required for the Authorization Code (PKCE) grant type. Select SHA-256 to hash the code verifier or Plain to use it as-is.

Code Verifier

Optional. To connect the authorization request to the token request, enter a cryptographically random string between 43 and 128 characters long. Use the letters A-Z and a-z, the numbers 0-9, and the characters -._~. If you leave this field empty, Tosca Cloud automatically generates a value.

Configure XML and Web Services (WS) security for your connection.

From the Elements to Generate dropdown menu, select which security elements you want to include in your messages. Then, select one of the following:

  • Action: Adds a SOAP action element to the SOAPAction header. By default, the system uses the existing SOAPAction header of the message. Disable the default to specify a custom action URL, for example http://CalculatorService/ICalculator/Add.

  • To: Adds an address element that specifies the recipient for your messages. By default, Tosca Cloud uses the URL from the connection and the resource identifier from the message. Disable the default to specify a custom address, for example https://webservice.toscacloud.com/signature.svc.

  • Timestamp: Adds a timestamp element that defines a time period during which the message is valid. Specify the time to live in seconds.

  • Signature: Adds a digital signature that signs selected elements of the message. Configure the signature settings below.

  • Username: Adds a username token in the message header for WS Security. Configure the username settings below.

Property

Description

Type of Signature

Select Signature in Security Header (SOAP Standard) to sign the SOAP message or Enveloped Signature to sign a specific element within the message.

Elements to Sign

Select which parts of the message to sign:

  • Body

  • Timestamp

  • To

  • Custom element

  • All

Custom Element Id

Enter the ID of the element to sign. Required when you select Custom element for Elements to Sign.

Canonicalization Algorithm

Select the canonicalization algorithm (opens in new tab). Canonicalization ensures that logically equivalent XML documents produce identical signatures.

Digest Algorithm

Select the digest algorithm (opens in new tab) to calculate the hash value that creates and verifies the signature.

Signature Method

To generate the signature, select the signature algorithm (opens in new tab).

Key Identifier Type

Select how to include the public key for signature validation:

  • Do not Include

  • RSA or DSA key value

  • Issuer and Serial Number

  • X509v3 Certificate Data

  • Binary Security Token

Certificate

Select the certificate type to use for the signature.

Property

Description

Username

Enter the username for the Web Services (WS) security token.

Password

Enter the password.

Password Type

Select Plain text to send the password as-is or Digest to send it in hashed format.

Add Nonce

Optional. Enable to include a unique random value that prevents replay attacks.

Add Created

Optional. Enable to include a creation timestamp for the token.

To route your API requests through a proxy server, specify its address, username, and password.

Configure additional settings, such as response timeout in milliseconds, to control how your connection behaves when it communicates with the API endpoint.

Edit a connection

To update any connection setting, select a connection from the list, change the values in the properties panel, then select Save.

What's next

Create API messages and start using your connections in your API tests.