Your AI Connector Docs

Authenticatie

Elk API-verzoek moet uw API-sleutel bevatten zodat Your AI Connector weet wie u bent en voor welk account actie moet worden ondernomen. U kunt de sleutel op vier verschillende manieren verzenden — ze werken allemaal op elk eindpunt dat API-sleutelauthenticatie accepteert, dus kies de methode die het beste bij uw configuratie past.

API-toegang is een betaalde functie. Als uw abonnement dit niet bevat, worden verzoeken afgewezen met een 403, zelfs als de sleutel zelf geldig is — zie De betaalde-functiepoort hieronder. Zie API-toegang om een sleutel te genereren.

Alleen HTTPS. Alle verzoeken moeten een beveiligde verbinding gebruiken. Gewone HTTP-verzoeken worden afgewezen voordat de authenticatie zelfs wordt uitgevoerd.

De vier methoden in één oogopslag

Methode Drager Wanneer te gebruiken
Query-parameter ?apiKey=YOUR_API_KEY Snelle tests en browser-URL’s
Header X-API-Key: YOUR_API_KEY Productie-integraties
Bearer-header Authorization: Bearer YOUR_API_KEY Productie-integraties
Firebase ID-token Authorization: Bearer <ID token> Alleen voor sessies van eigen apps

Wanneer er meer dan één aanwezig is, heeft de query-parameter voorrang, daarna de X-API-Key-header, en vervolgens het bearer-token. In de praktijk verstuurt u er altijd maar één.

1. Query-parameter — ?apiKey=

Voeg uw sleutel toe aan het einde van het webadres. Dit is de eenvoudigste vorm en werkt altijd, wat het ideaal maakt voor snelle tests, scripts en oudere tools.

cURL

curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()

Let op: Webadressen komen terecht in de browsergeschiedenis, servertoegangslogboeken en proxylogboeken. Geef voor alles wat verder gaat dan een snelle test de voorkeur aan een van de onderstaande headermethoden, zodat uw sleutel niet in leesbare tekst op de schijf wordt opgeslagen.

2. X-API-Key-header

Verzend de sleutel in een speciale header. Dit houdt de sleutel uit de URL en is de aanbevolen keuze voor productieomgevingen.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

3. Authorization: Bearer header

Je kunt de sleutel ook doorgeven als een standaard bearer-token. Dit is handig wanneer je HTTP-client of framework al ingebouwde ondersteuning heeft voor Authorization-headers.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()

De API onderscheidt automatisch je API-sleutel van een inlogtoken, dus deze methode werkt precies zoals X-API-Key.

4. Firebase ID-token (alleen voor first-party)

Als je een first-party app bouwt die gebruikers laat inloggen via de eigen inlogmethode van Your AI Connector, kun je het Firebase ID-token van die ingelogde gebruiker doorgeven als bearer-token in plaats van een API-sleutel:

Authorization: Bearer <Firebase ID token>

Het token wordt bij elk verzoek geverifieerd en gekoppeld aan het ingelogde account. Deze methode is alleen voor first-party app-sessies — je kunt deze tokens niet aanmaken vanuit een externe integratie en er is geen manier om er een te verkrijgen zonder de normale app-inlogprocedure te doorlopen. Gebruik voor server-to-server en third-party integraties een API-sleutel (methoden 1–3).

Wanneer gebruik je wat

  • Snelle tests en eenmalige scripts → queryparameter (?apiKey=). Het snelst te typen, werkt in een browser.
  • Productie-integraties en server-to-server-aanroepen → X-API-Key of Authorization: Bearer YOUR_API_KEY. Houdt de sleutel uit URL’s en logs.
  • First-party apps met een ingelogde Your AI Connector-gebruiker → Authorization: Bearer <Firebase ID token>.

Sleutelbereiken

Je account heeft één hoofd-API-sleutel — de sleutel onder Instellingen → Integraties → API-sleutel. Deze heeft volledige toegang tot alles wat het account kan doen.

Je kunt ook extra sleutels met bereik aanmaken: benoemde sleutels die alleen toegang hebben tot de delen van de API die jij kiest, bijvoorbeeld een alleen-lezen sleutel beperkt tot Analytics voor een rapportagedashboard. Een sleutel met bereik wordt op precies dezelfde manier verzonden als de hoofdsleutel (via een van de methoden 1–3 hierboven), maar wordt bij elk verzoek gecontroleerd op zijn eigen machtigingen:

  • Buiten de toegestane gebieden wordt de toegang geweigerd. Een schrijfactie met een alleen-lezen sleutel, of een aanroep naar een sectie waarvoor de sleutel geen toestemming heeft, resulteert in 403 — key_read_only of key_scope_denied in het error_code veld. De controle is bewust strikt: alles wat niet duidelijk binnen de toegestane gebieden van de sleutel valt, wordt geweigerd in plaats van doorgelaten. Als je dus een van die 403s ziet, dekt de sleutel simpelweg dat eindpunt niet.
  • Het heeft een eigen limietbudget. Een sleutel met bereik wordt afzonderlijk geteld van je hoofdsleutel, zodat een druk dashboard dat een sleutel met bereik gebruikt, niet het budget kan verbruiken waar je andere integraties van afhankelijk zijn. Je kiest dat budget per minuut wanneer je de sleutel aanmaakt.
  • Het kan geen API-sleutels beheren. Alleen de accounteigenaar — ingelogd of gebruikmakend van de hoofdsleutel — kan sleutels weergeven, aanmaken, bewerken, roteren of intrekken. Een sleutel met bereik kan nooit een ruimere sleutel voor zichzelf aanmaken.

Zie API-sleutels voor informatie over het aanmaken, bewerken en intrekken van sleutels met bereik.

De betaalde-functiepoort

API-toegang is een betaalde functie. Wanneer uw abonnement dit niet bevat, wordt een verzoek met een verder geldige sleutel afgewezen met 403:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

If you see this, check your plan or contact hi@youraiconnector.com. A missing or wrong key returns 401 instead:

{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}

Uw sleutel veilig houden

  • Behandel de sleutel als een wachtwoord. Je hoofdsleutel verleent volledige toegang tot je account. Als je een sleutel moet verstrekken aan een tool of persoon die slechts een deel van de toegang nodig heeft, maak dan in plaats daarvan een sleutel met bereik aan — zie Sleutelbereiken.
  • Houd het aan de serverzijde. Verwerk het nooit in browser-JavaScript, een mobiele app-bundel of enige code die een eindgebruiker kan lezen.
  • Sla het op in een secret manager of server-side configuratie, niet in broncodebeheer.
  • Roteer de sleutel als deze lekt. Genereer een nieuwe sleutel via het dashboard of roep POST https://api.youraiconnector.com/v1/api-keys/rotate aan — dit maakt de oude onmiddellijk ongeldig. Zie API-sleutels.
  • Gebruik altijd HTTPS zodat de sleutel tijdens het transport versleuteld is.

Volgende stappen