Automatically generate API Client credentials for an existing Connector

Connect Add-On
Ask about this Page
Copy for LLM
View as Markdown
This step-by-step guide outlines how to update your connect.yaml configuration file to automatically generate API Client credentials.

Requirements

Before you begin, ensure you have the following:

  • An existing Connector that uses connect.yaml for configuration.
  • Access to the commercetools API and the necessary credentials.
If you use automatically generated API Client credentials, then the API Client that you used to create the Deployment must have access to the manage_api_clients:{projectKey} scope. This helps ensure the necessary permissions for automatically creating credentials are stored within your Project. You must add the scope to the API Client that runs the Deployment; do not add the scope to the connect.yaml file of the Connector.
If you don't give access to the manage_api_clients:{projectKey} scope, then a 403 access denied error will occur when you try to deploy a Connector that is configured for automatically generating API Client credentials.

Update your configuration file

To enable automatic generation of API credentials, update your connect.yaml configuration file.
To prevent configuration conflicts, ensure that the connect.yaml file does not include any variables that will be automatically generated by the API Client generation feature. These autogenerated variables are provided at runtime and should not be manually defined in the configuration.
The following example shows a connect.yaml file with pre-generated commercetools credentials. With this configuration file, API Client will not be generated automatically.
Example connect.yaml file without automatic API Client generationyaml
deployAs:
  - name: service_app_name
    applicationType: service
    endpoint: /service
    scripts:
      postDeploy: npm run connector:post-deploy
      preUndeploy: npm run connector:pre-undeploy
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: Project key of the commercetools Project
          required: true
          default: 'default-key'
      securedConfiguration:
        - key: INTEGRATION_API_KEY
          description: API key for the integration
          required: true
        - key: CTP_CLIENT_ID
          description: commercetools client ID
          required: true
        - key: CTP_CLIENT_SECRET
          description: commercetools client secret
          required: true
        - key: CTP_SCOPE
          description: commercetools client scope
  - name: job_app_name
    applicationType: job
    endpoint: /job
    properties:
      schedule: '*/5 * * * *'
    configuration:
      standardConfiguration:
        - key: CTP_PROJECT_KEY
          description: Project key of the commercetools Project
          required: true
      securedConfiguration:
        - key: INTEGRATION_API_KEY
          description: API key for the integration
          required: true
        - key: CTP_CLIENT_ID
          description: commercetools client ID
          required: true
        - key: CTP_CLIENT_SECRET
          description: commercetools client secret
          required: true
        - key: CTP_SCOPE
          description: commercetools client scope
To enable automatic API Client generation, complete the following steps in your connect.yaml file:
  1. In the standardConfiguration object, remove the CTP_PROJECT_KEY variable with the commercetools project key: this key will be fetched automatically.
  2. In the securedConfiguration object, remove the variables with pre-generated commercetools credentials: CTP_CLIENT_ID, CTP_CLIENT_SECRET, and CTP_SCOPE.
  3. Add an inheritAs object and specify the scopes to include for automatically generated API Client credentials as a list in inheritAs.apiClient.scopes, for example manage_payments, manage_orders, manage_extensions (only for service application types that use API Extensions), and manage_subscriptions (only for event application types that use Subscriptions).
The resulting example connect.yaml looks as follows:
Example connect.yaml file with automatic API Client generationyaml
deployAs:
  - name: service_app_name
    applicationType: service
    endpoint: /service
    scripts:
      postDeploy: npm run connector:post-deploy
      preUndeploy: npm run connector:pre-undeploy
    configuration:
      securedConfiguration:
        - key: INTEGRATION_API_KEY
          description: API key for the integration
          required: true
  - name: job_app_name
    applicationType: job
    endpoint: /job
    properties:
      schedule: '*/5 * * * *'
    configuration:
      securedConfiguration:
        - key: INTEGRATION_API_KEY
          description: API key for the integration
          required: true
inheritAs:
  apiClient:
    scopes:
      - manage_payments
      - manage_orders
      - manage_subscriptions # only for event application types that use Subscriptions
      - manage_extensions # only for service application types that use API Extensions

Variables available in the Connect application

With the automatic generation of API Client credentials, the following environment variables will be available for your Connector:

FieldDescription
CTP_API_URLcommercetools API URL.
CTP_AUTH_URLAuthentication URL for the commercetools API.
CTP_CLIENT_IDAPI Client ID for the Connector.
CTP_PROJECT_KEYcommercetools Project key.
CTP_CLIENT_SECRETSecret key associated with the commercetools API Client.
CTP_SCOPEList of scopes assigned to the API credentials.