Instellingen: Privé integraties (Private Integrations)

Met Privé integraties (Private Integrations) maak je veilige koppelingen op maat tussen je Voluit Suite-account en andere apps. Je gebruikt ze bijvoorbeeld voor interne tools, geautomatiseerde workflows en eigen systemen die API-toegang nodig hebben, zonder dat je een openbare app hoeft te bouwen.

Belangrijk: in de API-documentatie vind je alle beschikbare endpoints en informatie over de gegevens die je verstuurt en terugkrijgt.

Wat zijn privé integraties?

Met een privé integratie koppel je je Voluit Suite-account via de API aan een andere app. Wil je een app koppelen? Dan heb je twee mogelijkheden:

• Zoek en installeer een geschikte app in de App-marketplace (App Marketplace).
• Bouw zelf een privé integratie via de API, eventueel met hulp van een ontwikkelaar.

Privé integraties maken die tweede optie veiliger. De belangrijkste voordelen:

• Beheer op één plek: je maakt tokens aan via de instellingen van je account en beheert ze daar ook.
• Gerichte toegang: je bepaalt welke rechten, ook wel scopes genoemd, de integratie krijgt. Zo beperk je tot welke gegevens en functies een ontwikkelaar toegang heeft.

Wat is het verschil tussen privé integraties en API-sleutels?

Privé integraties zijn een veiliger alternatief voor de oude API-sleutels en bieden meer mogelijkheden.

Waarom gebruik je een privé-integratietoken voor nieuwe toegang?

Een privé-integratietoken, ook wel Private Integration Token (PIT) genoemd, is de aanbevolen vervanger van een oude API-sleutel. Hiermee beheer je de toegang veiliger en flexibeler.

Oude API-sleutels die je langer dan 90 dagen niet gebruikt, kunnen in de instellingen de status Verlopen (Expired) krijgen. Je kunt geen nieuwe API-sleutels voor de oude API v1.0 meer aanmaken. Gebruik daarom een privé-integratietoken als je nieuwe toegang instelt of een bestaande integratie overzet naar een veiliger toegangsmodel.

Gebruik je nog een oude API-sleutel? Zet de integratie dan waar mogelijk over naar een privé-integratietoken.

Wat is het verschil tussen privé-integratietokens en OAuth2-toegangstokens?

Een privé-integratietoken is een vast toegangstoken. Het belangrijkste verschil met een OAuth2-toegangstoken is hoe je het aanmaakt en vernieuwt.

Hoe gebruik je een privé-integratietoken?

Je gebruikt je privé-integratietoken in de Authorization -header van je API-aanvraag, net als andere toegangstokens. Welke API-aanvragen je kunt uitvoeren, hangt af van de rechten die je aan de integratie hebt gegeven.

Een privé integratie testen met een API-aanvraag

Nadat je een privé integratie hebt aangemaakt, kun je deze testen door gegevens naar een API-endpoint te sturen. Gebruik daarvoor de juiste endpoint-URL.

Met dit voorbeeld voeg je een nieuw contact toe:

```bash

curl --request POST \

--url https://services.leadconnectorhq.com/contacts/ \

--header 'Authorization: <YOUR PRIVATE INTEGRATION TOKEN>' \

--header 'Content-Type: application/json' \

--header 'Version: 2021-07-28' \

--data '{

"firstName": "John",

"lastName": "Doe",

"email": "john.doe@example.com",

"phone": "+1234567890",

"locationId": "LOCATION_ID"

}'

```

Vervang in dit voorbeeld:

• LOCATION_ID  door de ID van je account. De technische veldnaam locationId  blijft ongewijzigd.
• <YOUR PRIVATE INTEGRATION TOKEN>  in de Authorization -header door je eigen privé-integratietoken.

Waar vind je privé integraties?

Ga naar Instellingen (Settings) → Privé integraties (Private Integrations). Zie je dit onderdeel niet? Controleer dan of de functie in Labs is ingeschakeld.

Een privé integratie aanmaken

Let op: je kunt maximaal 20 privé-integratietokens per account aanmaken. Zo kun je voor verschillende integraties en workflows aparte tokens gebruiken.

Stap 1: maak een nieuwe integratie aan

Klik op Nieuwe integratie aanmaken (Create new Integration).

Stap 2: geef je integratie een naam en beschrijving

Kies een naam en beschrijving waaraan jij en je team kunnen zien waarvoor de integratie bedoeld is.

Stap 3: selecteer de rechten

Kies tot welke gegevens en functies van je account de integratie toegang krijgt. Selecteer alleen de rechten die de integratie nodig heeft. Zo beperk je de toegang tot je gegevens.

Stap 4: kopieer je token

Kopieer het aangemaakte token en deel het met de ontwikkelaar van de app die je wilt koppelen. Deel het alleen met partijen die je vertrouwt en zet het nooit openbaar.

Let op: kopieer je token meteen en bewaar het veilig. Je kunt het later niet opnieuw bekijken of kopiëren.

Je token veilig houden

We raden je aan om je privé-integratietokens elke 90 dagen te vervangen. Dit heet ook wel tokenrotatie. Je maakt dan een nieuw token aan en laat het oude token vervallen.

Stap 1: open je integratie

Ga naar privé integraties onder instellingen en klik op de integratie waarvan je het token wilt vervangen.

Stap 2: kies voor vervanging met een overgangsperiode

Klik op Token vervangen en later laten verlopen (Rotate and expire this token later).

Stap 3: bevestig je keuze

Lees de waarschuwing en klik op Doorgaan (Continue) als je het token wilt vervangen.

Stap 4: werk het token bij in je gekoppelde app

Kopieer het nieuwe token en vervang het oude token in de app die je hebt gekoppeld.

Je hebt een overgangsperiode van 7 dagen waarin zowel het oude als het nieuwe token werkt. Daarna verloopt het oude token. Tijdens die 7 dagen kun je kiezen voor:

• Tokenvervanging annuleren (Cancel rotation): bijvoorbeeld als je ontwikkelaar meer tijd nodig heeft om het token in de gekoppelde app bij te werken.
• Nu laten verlopen (Expire Now): bijvoorbeeld als je het nieuwe token al in de gekoppelde app hebt ingesteld.

Let op: kopieer het nieuwe token meteen en bewaar het veilig. Je kunt het later niet opnieuw bekijken of kopiëren.

Wat doe je als je token is gelekt?

Stap 1: open je integratie

Ga naar privé integraties onder instellingen en klik op de integratie waarvan het token is gelekt.

Stap 2: vervang het token en laat het oude direct verlopen

Klik op Token vervangen en direct laten verlopen (Rotate and expire this token now).

Stap 3: bevestig je keuze

Lees de waarschuwing en klik op Doorgaan (Continue) als je het token wilt vervangen.

Stap 4: werk het token bij in je gekoppelde app

Kopieer het nieuwe token en vervang het oude token in de app die je hebt gekoppeld.

Let op: kopieer het nieuwe token meteen en bewaar het veilig. Je kunt het later niet opnieuw bekijken of kopiëren.

Rechten aanpassen zonder je token te vervangen

Je kunt de naam, beschrijving en rechten van een privé integratie op elk moment aanpassen. Daarvoor hoef je geen nieuw token aan te maken.

Stap 1: open de instellingen van je integratie

Ga naar privé integraties onder instellingen. Open het menu met de drie puntjes bij de integratie en kies Bewerken (Edit).

Stap 2: pas de naam en beschrijving aan

Werk de naam en beschrijving bij als dat nodig is. Klik daarna op Volgende (Next).

Stap 3: pas de rechten aan

Wijzig de rechten die de integratie in je account krijgt. Selecteer alleen de rechten die nodig zijn om je gegevens te beschermen. Klik op Bijwerken (Update) om je wijzigingen op te slaan.

Let op: door de gegevens of rechten van je integratie aan te passen, wordt geen nieuw token aangemaakt. Je bestaande token blijft werken.

Een privé integratie verwijderen

Gebruik je de gekoppelde app niet meer? Dan kun je de privé integratie verwijderen. Ga naar privé integraties onder instellingen, open het menu met de drie puntjes bij de integratie en kies Verwijderen (Delete).