Configure the REST API server

Before you can start using REST API operations with Transfer CFT, you need to set a few parameters in the Transfer CFT configuration.

Before you start

The REST server is a Copilot service. To start the REST server, use the copstart command to start Copilot.


Transfer CFT requires the following configuration settings before you can use REST API.

  1. Enable the Copilot REST API if you did not do so during installation.
  2. CFTUTIL uconfset id=copilot.restapi.enable, value=yes
  3. Optionally, you can change the REST API server port as follows (default 1768):
  4. CFTUTIL uconfset id=copilot.restapi.serverport, value=<new port>
  5. You require a secure SSL/TLS communication between the client (REST or browser) and the REST server. When using Central Governance, the REST API server automatically uses the SSL business certificate generated during the registration; there is no need to perform this step. This certificate is stored in the internal PKI base and is identified by the Transfer CFT instance ID (uconf:cft.instance_id).
  6. Otherwise, use UCONF to set the following Copilot parameters to configure the SSL certificate.
  7. CFTUTIL uconfset id=copilot.ssl.SslCertFile, value=<ssl pkcs12 certificate for copilot>

    CFTUTIL uconfset id=copilot.ssl.SslCertPassword, value=<ssl pkcs12 certificate password>

  8. These parameter settings are described in Install a certificate on the server side.
  9. Specify the authentication method, as the client must provide credentials (user/password) to the REST server. Set the UCONF the copilot.restapi.authentication_method parameter.
  10. Example
  11. CFTUTIL uconfset id=copilot.restapi.authentication_method, value=system

The supported authentication methods are:

Authentication method copilot.restapi.authentication_method Details
Operating System system

The user/password is checked against the operating system.

Note We strongly recommend that you set copilot.misc.createprocessasuser=yes when using the system option.

On Unix, you must use cftsu to create users. Refer to Using system users UNIX for detailed instructions.

Access Management am

This methods uses an indirection towards the Access Management system. The user/password is checked by the configured access management system: Central Governance (PassPort AM), or internal AM.

xfbadm database

(UNIX only)


The user/password is checked using the xfbadm base (see the xfbadmusr and xfbadmgrp utilities).

REST API server authentication method




Parameter Type Default Description
copilot.restapi.enable bool No

Enable/disable the REST API service:

  • Yes: enable
  • No: disable
copilot.restapi.serverport int 1768

REST API server port.

copilot.restapi.authentication_method string

system (Windows)

xfbadm (UNIX)

Defines authentication method.
copilot.restapi.nb_workers int 1 Number of activated workers that process the REST API requests.
copilot.restapi.maxclient int 256 Number of client connections handled per REST worker.
copilot.restapi.coms_id string coms

The TCPIP CFTCOM object identifier used by the REST API server to communicate with the Transfer CFT server.

Leave empty to use the COM file instead.

copilot.restapi.catalog.retry_delay int 5
  • The delay between retries in seconds. The Copilot server checks the request status in catalog every retry_delay seconds.
  • The delay between retries in seconds. The Copilot server checks the request status in catalog every retry_delay seconds.
copilot.restapi.catalog.retry_timeout int 30

The default value of the apiTimeout parameter as defined in the request URL.

Available exclusively for POST requests.

Related Links