---
title: Clés d'intégration
excerpt: Créez, listez, consultez, modifiez et supprimez les clés d'intégration CRM d'un compte client.
order: 8
---

Une **clé d'intégration** contient les identifiants qu'utilise CX-Engine pour connecter un compte client à un système tiers (Salesforce, HubSpot, Dynamics, ConnectWise, un webhook…).

Tous les endpoints de cette section sont **scopés au workspace**, requièrent le scope OAuth `client` et agissent sur un seul compte client, sélectionné avec le paramètre de requête `customer_account` (voir [Choix du compte client](/fr/docs/cx-api/smart-routings#choix-du-compte-client)).

**En-têtes :** `Authorization: Bearer {token-workspace}`

> **Les identifiants ne sont jamais renvoyés.** Les secrets sont stockés chiffrés et ne figurent dans aucune réponse de l'API. L'attribut `has_keys` indique seulement si des identifiants sont enregistrés.

---

## Permissions

| Endpoint | Permission requise |
|---|---|
| `GET /api/integration-keys` | `customer-integration.view` |
| `GET /api/integration-keys/{id}` | `customer-integration.view` |
| `POST /api/integration-keys` | `customer-integration.create` |
| `PUT /api/integration-keys/{id}` | `customer-integration.edit` |
| `DELETE /api/integration-keys/{id}` | `customer-integration.delete` |

L'utilisateur authentifié doit également avoir accès au compte client sélectionné.

---

## L'objet clé d'intégration

```json
{
  "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
}
```

| Champ | Description |
|---|---|
| `outsource_provider` | Système connecté : `active_campaign`, `atera`, `bluerocktel`, `connectwise`, `dynamics`, `glpi`, `hubspot`, `neoteem`, `salesforce`, `sellsy`, `webhook` |
| `type` | Type d'authentification : `none`, `token`, `app_token`, `oauth`, `oauth_pat`, `oauth_client_credentials`, `oauth_azure`, `password`, `basic`, `connectwise`, `oauth_password`, `header_token` |
| `uid` | Identifiant du flux OAuth, pour les clés OAuth |
| `requires_action` | `true` tant que l'autorisation OAuth n'a pas été finalisée |
| `enabled` | Clé utilisée ou non |
| `has_keys` | Des identifiants sont enregistrés pour cette clé |
| `integration_id` | Ancien identifiant d'intégration, peut valoir `null` |

---

## GET /api/integration-keys

Retourne toutes les clés d'intégration du client sélectionné sous forme de tableau JSON simple (non paginé).

**Paramètres de requête**

| Paramètre | Type | Requis | Description |
|---|---|---|---|
| `customer_account` | string | oui | Code de compte client |

**Réponse `200`** : tableau d'objets clé d'intégration

---

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

Retourne une clé d'intégration.

**Paramètres de requête**

| Paramètre | Type | Requis | Description |
|---|---|---|---|
| `customer_account` | string | oui | Code de compte client |

**Réponse `200`** : objet clé d'intégration

**Réponse `404`** : la clé n'appartient pas au client sélectionné

---

## POST /api/integration-keys

Connecte une nouvelle clé d'intégration au client sélectionné. Le corps doit être un objet JSON. La clé est toujours rattachée au client sélectionné avec `customer_account` : `customer_id`, `keyable_id`, `keyable_type` et `integration_id` sont ignorés s'ils sont envoyés.

**Paramètres de requête**

| Paramètre | Type | Requis | Description |
|---|---|---|---|
| `customer_account` | string | oui | Code de compte client |

**Corps de la requête**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `outsource_provider` | string | oui | Système connecté (voir le tableau ci-dessous) |
| `type` | string | oui | Type d'authentification, parmi les types autorisés pour le fournisseur |
| `name` | string | oui | Nom affiché (2 à 255 caractères) |
| `enabled` | boolean | non | `true` par défaut |
| `keys` | object | selon `type` | Identifiants (voir ci-dessous) |

**`type` autorisés par fournisseur**

| `outsource_provider` | `type` autorisés |
|---|---|
| `active_campaign` | `header_token` |
| `atera` | `token` |
| `bluerocktel` | `password` |
| `connectwise` | `connectwise` |
| `dynamics` | `oauth_azure`, `oauth_client_credentials` |
| `glpi` | `app_token` |
| `hubspot` | `oauth`, `token` |
| `neoteem` | `basic` |
| `salesforce` | `oauth` |
| `sellsy` | `oauth_pat` |
| `webhook` | `none`, `basic`, `token`, `password`, `oauth_client_credentials`, `oauth_password` |

**Champs de `keys` par `type`**

| `type` | Champs requis | Champs optionnels |
|---|---|---|
| `none` | — | `api_url` |
| `token` | — | `api_url`, `access_token`, `refresh_token`, `key_placement` (`header` ou `request_parameter`), `header_name` (requis quand `key_placement` vaut `request_parameter`), `header_prefix` |
| `header_token` | `api_url`, `access_token` | — |
| `app_token` | `api_url`, `client_id`, `client_secret` | — |
| `password`, `basic` | `user_login`, `user_password` | `api_url` |
| `connectwise` | `api_url`, `tenant_id`, `client_id`, `user_login`, `user_password` | — |
| `oauth_client_credentials` | `api_url`, `client_id`, `client_secret` | `tenant_id`, `scope` |
| `oauth_password` | `api_url`, `client_id`, `client_secret`, `user_login`, `user_password` | — |
| `oauth_pat` | `client_id`, `client_secret` | `expires_in`, `expires_at` |
| `oauth_azure` | `api_url` | — |
| `oauth` | — | — |

**Exemple**

```json
{
  "outsource_provider": "atera",
  "type": "token",
  "name": "Atera production",
  "keys": {
    "api_url": "https://app.atera.com/api/v3",
    "access_token": "votre-cle-api-atera"
  }
}
```

**Réponse `201`**

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

Pour les types OAuth (`oauth`, `oauth_azure`), la clé est créée avec `requires_action: true` et `action` décrit l'autorisation à finaliser : ouvrez `action.redirect_url` dans un navigateur pour accorder l'accès.

```json
{
  "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?..."
  }
}
```

**Réponse `400`** : échec de validation : `outsource_provider` manquant ou inconnu, `type` non autorisé pour le fournisseur, `name` manquant ou `keys` invalides pour le type

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

---

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

Renomme, active ou désactive une clé d'intégration, ou remplace ses identifiants. Le corps doit être un objet JSON.

**Paramètres de requête**

| Paramètre | Type | Requis | Description |
|---|---|---|---|
| `customer_account` | string | oui | Code de compte client |

**Corps de la requête**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `name` | string | non | Nom affiché (2 à 255 caractères) |
| `enabled` | boolean | non | Active ou désactive la clé |
| `keys` | object | non | Nouveaux identifiants, validés selon le `type` actuel de la clé (mêmes champs qu'à la création). Ils remplacent les identifiants enregistrés. Non acceptés pour les clés OAuth (`oauth`, `oauth_azure`) : supprimez puis recréez la clé |

Le propriétaire, le fournisseur et le type d'une clé ne peuvent pas être modifiés : envoyer `customer_id`, `keyable_id`, `keyable_type`, `integration_id`, `outsource_provider`, `type`, `uid` ou `requires_action` renvoie une `400`.

**Réponse `201`** : l'objet clé d'intégration modifié

**Réponse `400`** : échec de validation (champ interdit, `keys` invalides pour le type de la clé)

**Réponse `422`** : `keys` envoyés pour une clé OAuth

**Réponse `404`** : la clé n'appartient pas au client sélectionné

---

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

Supprime une clé d'intégration.

**Paramètres de requête**

| Paramètre | Type | Requis | Description |
|---|---|---|---|
| `customer_account` | string | oui | Code de compte client |

**Réponse `200`**

```json
{ "response": "element deleted" }
```

**Réponse `404`** : la clé n'appartient pas au client sélectionné