Autentificare #

Fiecare cerere API trebuie să conțină cheia ta API, astfel încât Your AI Connector să știe cine ești și pentru ce cont să acționeze. Poți trimite cheia în patru moduri diferite — toate funcționează pe fiecare endpoint care acceptă autentificarea prin cheie API, așa că alege-o pe cea care se potrivește configurației tale.

Accesul API este o funcționalitate plătită. Dacă planul tău nu o include, cererile sunt respinse cu un 403 chiar și atunci când cheia în sine este validă — consultă Poarta funcționalităților plătite de mai jos. Pentru a genera o cheie, consultă Acces API.

Doar HTTPS. Toate cererile trebuie să utilizeze o conexiune securizată. Cererile HTTP simple sunt respinse înainte ca autentificarea să ruleze.

Cele patru metode pe scurt #

Când este prezentă mai mult de una, parametrul de interogare are prioritate, urmat de antetul X-API-Key, apoi de tokenul bearer. În practică, trimiți oricum doar una singură.

1. Parametru de interogare — ?apiKey= #

Adaugă cheia la sfârșitul adresei web. Aceasta este cea mai simplă formă și funcționează întotdeauna, ceea ce o face ideală pentru teste rapide, scripturi și orice instrumente mai vechi.

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

Atenție: Adresele web ajung în istoricul browserului, în jurnalele de acces ale serverului și în jurnalele proxy. Pentru orice altceva în afară de un test rapid, preferă una dintre metodele de antet de mai jos, astfel încât cheia ta să nu fie scrisă pe disc la vedere.

2. Antet X-API-Key #

Trimite cheia într-un antet dedicat. Aceasta o menține în afara URL-ului și este alegerea recomandată pentru producție.

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. Antet Authorization: Bearer #

De asemenea, poți transmite cheia ca un bearer token standard. Acest lucru este util atunci când clientul sau framework-ul tău HTTP are deja suport încorporat pentru antetele Authorization.

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-ul distinge automat cheia ta API de un token de autentificare, deci această metodă funcționează exact ca X-API-Key.

4. Token ID Firebase (doar pentru aplicații proprii) #

Dacă dezvolți o aplicație proprie care autentifică utilizatorii prin sistemul de login al Your AI Connector, poți transmite tokenul ID Firebase al utilizatorului autentificat ca bearer token în loc de o cheie API:

Authorization: Bearer <Firebase ID token>

Tokenul este verificat la fiecare cerere și este asociat contului autentificat. Această metodă este destinată exclusiv sesiunilor aplicațiilor proprii — nu poți genera aceste tokenuri dintr-o integrare externă și nu există nicio modalitate de a obține unul fără a trece prin procesul normal de autentificare în aplicație. Pentru integrări server-la-server și terțe părți, folosește o cheie API (metodele 1–3).

Când să folosești fiecare metodă #

• Teste rapide și scripturi unice → parametru de interogare (?apiKey=). Cel mai rapid de tastat, funcționează într-un browser.
• Integrări în producție și apeluri server-la-server → X-API-Key sau Authorization: Bearer YOUR_API_KEY. Păstrează cheia în afara URL-urilor și a jurnalelor.
• Aplicații proprii cu un utilizator Your AI Connector autentificat → Authorization: Bearer <Firebase ID token>.

Domenii de aplicare ale cheilor #

Contul tău are o cheie API principală — cea din Setări → Integrări → Cheie API. Aceasta are acces complet la tot ceea ce poate face contul.

Poți crea, de asemenea, chei cu domeniu limitat: chei denumite care accesează doar părțile din API pe care le alegi, de exemplu, o cheie de tip „doar citire” limitată la Analize pentru un tablou de bord de raportare. O cheie cu domeniu limitat este trimisă exact ca cheia principală (oricare dintre metodele 1–3 de mai sus), dar este verificată în raport cu propriile permisiuni la fiecare solicitare:

• În afara zonelor permise, accesul este refuzat. O scriere cu o cheie de tip „doar citire” sau un apel către o secțiune pentru care cheia nu a primit permisiuni va returna 403 — key_read_only sau key_scope_denied în câmpul error_code. Verificarea este în mod deliberat strictă: orice nu se află clar în interiorul zonelor permise ale cheii este refuzat în loc să fie permis, deci dacă vezi una dintre acele 403, cheia pur și simplu nu acoperă acel endpoint.
• Are propriul buget de limitare a ratei. O cheie cu domeniu limitat este contorizată separat de cheia ta principală, astfel încât un tablou de bord intens utilizat care folosește o cheie cu domeniu limitat nu poate consuma alocarea de care depind celelalte integrări ale tale. Alegi acel buget pe minut atunci când creezi cheia.
• Nu poate gestiona cheile API. Doar proprietarul contului — autentificat sau folosind cheia principală — poate lista, crea, edita, roti sau revoca chei. O cheie cu domeniu limitat nu poate genera niciodată o cheie cu permisiuni mai extinse.

Consultă Chei API pentru a afla cum să creezi, editezi și revoci chei cu domeniu limitat.

Restricționarea funcțiilor cu plată #

Accesul la API este o funcționalitate plătită. Atunci când planul tău nu o include, o cerere cu o cheie altfel validă este respinsă cu 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"
}

Păstrarea cheii în siguranță #

• Tratează cheia ca pe o parolă. Cheia ta principală oferă acces complet la contul tău. Dacă trebuie să oferi o cheie unui instrument sau unei persoane care are nevoie doar de o parte din acces, creează în schimb o cheie cu domeniu limitat — consultă Domenii de aplicare ale cheilor.
• Păstreaz-o pe partea de server. Nu o include niciodată în JavaScript-ul browserului, într-un pachet de aplicație mobilă sau în orice cod pe care un utilizator final îl poate citi.
• Stocheaz-o într-un manager de secrete sau în configurația de pe partea de server, nu în controlul sursei.
• Rotește-o dacă există scurgeri de date. Generează o cheie nouă din tabloul de bord sau apelează POST https://api.youraiconnector.com/v1/api-keys/rotate — acest lucru invalidează imediat cheia veche. Consultă Chei API.
• Folosește întotdeauna HTTPS astfel încât cheia să fie criptată în tranzit.

Pașii următori #

• Introducere — prima ta cerere și ghidurile de resurse.
• Erori și paginare — gestionează eșecurile și parcurge rezultatele pagină cu pagină.
• Chei API — schimbă, revocă și verifică utilizarea cheii tale.