Integration Keys

An integration key holds the credentials CX-Engine uses to connect a customer account to a third-party system (Salesforce, HubSpot, Dynamics, ConnectWise, a webhook…).

All endpoints in this section are workspace-scoped, require the client OAuth scope and act on a single customer account, selected with the customer_account query parameter (see Selecting the customer account).

Headers: Authorization: Bearer {workspace-token}

Credentials are never returned. Secrets are stored encrypted and are not part of any API response. The has_keys attribute only tells you whether credentials are stored.

#Permissions

The authenticated user must also have access to the selected customer account.

#The integration key object

{
  "id": 7,
  "uid": "70c7ee70-3e75-4dd3-a728-f435af607db4",
  "integration_id": null,
  "outsource_provider": "salesforce",
  "customer_id": 12,
  "keyable_type": "customer",
  "keyable_id": 12,
  "enabled": true,
  "requires_action": false,
  "name": "Salesforce production",
  "type": "oauth",
  "created_at": "2025-02-10T10:12:00.000000Z",
  "updated_at": "2025-02-10T10:15:31.000000Z",
  "has_keys": true
}

#GET /api/integration-keys

Returns all integration keys of the selected customer as a plain JSON array (not paginated).

Query parameters

Response 200 — array of integration key objects

#GET /api/integration-keys/{id}

Returns a single integration key.

Query parameters

Response 200 — integration key object

Response 404 — the key does not belong to the selected customer

#POST /api/integration-keys

Connects a new integration key to the selected customer. The body must be a JSON object. The key is always attached to the customer selected with customer_account: customer_id, keyable_id, keyable_type and integration_id are ignored if sent.

Query parameters

Request body

Allowed type per provider

keys fields per type

Example

{
  "outsource_provider": "atera",
  "type": "token",
  "name": "Atera production",
  "keys": {
    "api_url": "https://app.atera.com/api/v3",
    "access_token": "your-atera-api-key"
  }
}

Response 201

{
  "entity": { "id": 8, "outsource_provider": "atera", "type": "token", "name": "Atera production", "enabled": true, "requires_action": false, "has_keys": true, "...": "..." },
  "action": null
}

For OAuth types (oauth, oauth_azure), the key is created with requires_action: true and action describes the authorization to complete: open action.redirect_url in a browser to grant access.

{
  "entity": { "id": 9, "outsource_provider": "salesforce", "type": "oauth", "requires_action": true, "...": "..." },
  "action": {
    "type": "oauth",
    "provider": "salesforce",
    "uid": "70c7ee70-3e75-4dd3-a728-f435af607db4",
    "requires_action": true,
    "redirect_url": "https://login.salesforce.com/services/oauth2/authorize?..."
  }
}

Response 400 — validation failure: missing or unknown outsource_provider, type not allowed for the provider, missing name, or invalid keys for the type

{
  "response": "bad request: please check body parameters.",
  "hint": ["The selected type is invalid."]
}

#PUT /api/integration-keys/{id}

Renames, enables or disables an integration key, or replaces its credentials. The body must be a JSON object.

Query parameters

Request body

The ownership, provider and type of a key cannot be changed: sending customer_id, keyable_id, keyable_type, integration_id, outsource_provider, type, uid or requires_action returns a 400.

Response 201 — the updated integration key object

Response 400 — validation failure (forbidden field, invalid keys for the key type)

Response 422 — keys sent for an OAuth key

Response 404 — the key does not belong to the selected customer

#DELETE /api/integration-keys/{id}

Deletes an integration key.

Query parameters

Response 200

{ "response": "element deleted" }

Response 404 — the key does not belong to the selected customer