Your AI Connector Docs

Autentisering

Varje API-anrop måste innehålla din API-nyckel så att Your AI Connector vet vem du är och vilket konto som ska användas. Du kan skicka nyckeln på fyra olika sätt — alla fungerar på varje slutpunkt som accepterar API-nyckelautentisering, så välj det som passar din konfiguration bäst.

API-åtkomst är en betalfunktion. Om din plan inte inkluderar den, avvisas anrop med ett 403 även om själva nyckeln är giltig — se Spärr för betalfunktioner nedan. För att generera en nyckel, se API-åtkomst.

Endast HTTPS. Alla anrop måste använda en säker anslutning. Vanliga HTTP-anrop avvisas innan autentiseringen ens körs.

De fyra metoderna i korthet

Metod Bärare När den ska användas
Frågeparameter ?apiKey=YOUR_API_KEY Snabba tester och webbadresser i webbläsaren
Header X-API-Key: YOUR_API_KEY Produktionsintegrationer
Bearer-header Authorization: Bearer YOUR_API_KEY Produktionsintegrationer
Firebase ID-token Authorization: Bearer <ID token> Endast för förstapartsapp-sessioner

När mer än en metod används har frågeparametern högst prioritet, följt av X-API-Key-headern och sedan Bearer-token. I praktiken skickar du bara en.

1. Frågeparameter — ?apiKey=

Lägg till din nyckel i slutet av webbadressen. Detta är den enklaste formen och fungerar alltid, vilket gör den idealisk för snabba tester, skript och äldre verktyg.

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()

Observera: Webbadresser hamnar i webbläsarhistorik, serverloggar och proxyloggar. För allt utöver ett snabbt test bör du föredra en av header-metoderna nedan så att din nyckel inte skrivs till disk i klartext.

2. X-API-Key-header

Skicka nyckeln i en dedikerad header. Detta håller den borta från webbadressen och är det rekommenderade valet för produktion.

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-huvud

Du kan även skicka nyckeln som en standard bearer-token. Detta är praktiskt när din HTTP-klient eller ditt ramverk redan har inbyggt stöd för Authorization-huvuden.

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()

API:et skiljer automatiskt din API-nyckel från en inloggningstoken, så den här metoden fungerar precis som X-API-Key.

4. Firebase ID-token (endast förstapart)

Om du bygger en förstapartsapp som loggar in användare via Your AI Connectors egen inloggning, kan du skicka den inloggade användarens Firebase ID-token som en bearer-token istället för en API-nyckel:

Authorization: Bearer <Firebase ID token>

Token verifieras vid varje anrop och mappas till det inloggade kontot. Denna metod är endast för förstapartsapp-sessioner — du kan inte skapa dessa tokens från en extern integration, och det finns inget sätt att erhålla en utan att gå igenom den vanliga app-inloggningen. För server-till-server- och tredjepartsintegrationer, använd en API-nyckel (metod 1–3).

När ska man använda vad

  • Snabba tester och engångsskript → frågeparameter (?apiKey=). Snabbast att skriva, fungerar i en webbläsare.
  • Produktionsintegrationer och server-till-server-anrop → X-API-Key eller Authorization: Bearer YOUR_API_KEY. Håller nyckeln borta från URL:er och loggar.
  • Förstapartsappar med en inloggad Your AI Connector-användare → Authorization: Bearer <Firebase ID token>.

Nyckelomfång

Ditt konto har en huvud-API-nyckel — den som finns under Inställningar → Integrationer → API-nyckel. Den har full åtkomst till allt som kontot kan göra.

Du kan även skapa extra nycklar med begränsat omfång: namngivna nycklar som endast når de delar av API:et du väljer, till exempel en skrivskyddad nyckel begränsad till Analys för en rapportpanel. En nyckel med begränsat omfång skickas på exakt samma sätt som huvudnyckeln (någon av metoderna 1–3 ovan), men den kontrolleras mot sina egna behörigheter vid varje anrop:

  • Utanför sina tillåtna områden nekas den. En skrivåtgärd med en skrivskyddad nyckel, eller ett anrop till en sektion som nyckeln inte har tilldelats, returneras som 403 — key_read_only eller key_scope_denied i fältet error_code. Kontrollen är medvetet strikt: allt som inte tydligt ligger inom nyckelns tillåtna områden nekas istället för att släppas igenom, så om du ser ett av dessa 403-fel, täcker nyckeln helt enkelt inte den slutpunkten.
  • Den har sin egen budget för hastighetsbegränsning. En nyckel med begränsat omfång räknas separat från din huvudnyckel, så en upptagen instrumentpanel som använder en begränsad nyckel kan inte förbruka den kvot som dina andra integrationer är beroende av. Du väljer den budgeten per minut när du skapar nyckeln.
  • Den kan inte hantera API-nycklar. Endast kontoinnehavaren — inloggad eller med huvudnyckeln — kan lista, skapa, redigera, rotera eller återkalla nycklar. En nyckel med begränsat omfång kan aldrig skapa en nyckel med bredare behörighet.

Se API-nycklar för hur du skapar, redigerar och återkallar nycklar med begränsat omfång.

Spärr för betalfunktioner

API-åtkomst är en betalfunktion. När din plan inte inkluderar den, avvisas en begäran med en i övrigt giltig nyckel med 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"
}

Håll din nyckel säker

  • Behandla nyckeln som ett lösenord. Din huvudnyckel ger full åtkomst till ditt konto. Om du behöver ge en nyckel till ett verktyg eller en person som bara behöver en del av åtkomsten, skapa istället en nyckel med begränsat omfång — se Nyckelomfång.
  • Håll den på serversidan. Bädda aldrig in den i webbläsar-JavaScript, ett paket för mobilappar eller någon kod som en slutanvändare kan läsa.
  • Lagra den i en hemlighetshanterare eller serverkonfiguration, inte i källkodshantering.
  • Rotera den om den läcker. Generera en ny nyckel från instrumentpanelen eller anropa POST https://api.youraiconnector.com/v1/api-keys/rotate — detta gör omedelbart den gamla ogiltig. Se API-nycklar.
  • Använd alltid HTTPS så att nyckeln krypteras under transport.

Nästa steg