API pentru cheile API #

Aceste endpoint-uri vă permit să gestionați cheile API ale contului dvs. prin cod. Toate operează exclusiv asupra cheilor contului care efectuează apelul.

Există două tipuri de chei și acestea se află pe căi separate:

• Cheia principală — singura cheie cu acces complet disponibilă în Setări → Integrări → Cheie API. Puteți vizualiza previzualizarea mascată a acesteia, verifica utilizarea limitei de rată, o puteți roti sau revoca. Acestea sunt endpoint-urile /api-keys/current, /api-keys/rotate și /api-keys/usage de mai jos.
• Chei cu domeniu limitat (Scoped keys) — chei suplimentare, denumite, pe care le creați pentru o sarcină specifică, fiecare fiind limitată la părțile din API pe care le alegeți. Acestea sunt endpoint-urile /api-keys și /api-keys/{id} din secțiunea Chei cu domeniu limitat. Nimic din cheia principală nu se modifică atunci când creați una; integrările existente continuă să funcționeze neafectate.

Toate căile de mai jos sunt relative la URL-ul de bază al API-ului:

https://api.youraiconnector.com/v1

Fiecare cerere trebuie autentificată. Consultați Autentificare pentru cele patru metode acceptate. Exemplele de aici utilizează antetul X-API-Key (și o formă de parametru de interogare pentru cURL).

Citiți mai întâi acest lucru. Rotirea sau revocarea cheii dvs. intră în vigoare imediat. În momentul în care oricare dintre apeluri reușește, vechea cheie încetează să mai funcționeze — fiecare integrare care o utilizează în continuare va începe să primească erori 401. Planificați acest lucru: rotiți cheia în timpul unei ferestre de mentenanță și actualizați imediat toate integrările.

Obținerea metadatelor cheii curente #

Returnează cheia activă: cheia completă în api_key atunci când există o copie recuperabilă, o previzualizare mascată (primele 4 și ultimele 4 caractere) și, atunci când este disponibilă, data la care a fost creată. api_key este null pentru cheile create înainte ca copiile recuperabile să fie păstrate — rotiți o dată și noua cheie va putea fi afișată din nou mai târziu.

GET /api-keys/current

cURL

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

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

Răspuns

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}

Dacă contul nu are nicio cheie API, răspunsul este 404 cu { "success": false, "error": "No API key found for this account" }.

Obținerea utilizării limitei de rată #

Returnează utilizarea limitei de rată pentru fereastra curentă: limita de cereri per fereastră, câte cereri au fost contorizate până acum, câte au rămas și când se resetează fereastra. Utilizați acest lucru pentru a construi un sistem de limitare a traficului (throttling) pe partea de client, astfel încât integrarea dvs. să se oprească înainte de a primi răspunsuri 429.

GET /api-keys/usage

cURL

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

JavaScript

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

Python

import requests

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

Răspuns

{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}

Dacă nu au fost înregistrate cereri în fereastra curentă, utilizarea este raportată ca zero, iar răspunsul include un câmp note care explică motivul.

Rotirea cheii #

Generează o nouă cheie API și invalidează cheia anterioară în același pas. Utilizați această funcție dacă suspectați că cheia dvs. a fost compromisă sau ca parte a unei politici regulate de rotație a credențialelor.

POST /api-keys/rotate

Noua cheie este afișată o singură dată. Aceasta este returnată în acest răspuns și nu mai poate fi recuperată ulterior în întregime — stocați-o în siguranță imediat ce o primiți. Cheia anterioară încetează să mai funcționeze în momentul în care acest apel reușește, așa că actualizați fiecare integrare care o utiliza.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Răspuns

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}

Revocarea cheii #

Șterge definitiv cheia API a contului dumneavoastră. Revocarea este imediată: fiecare cerere ulterioară care utilizează cheia revocată — inclusiv integrări precum Make, Zapier sau scripturi personalizate — este respinsă cu un 401. Pentru a restabili accesul API ulterior, generați o cheie nouă din setările contului în timp ce sunteți conectat la aplicație.

DELETE /api-keys/current

Nu există nicio posibilitate de anulare. Spre deosebire de rotație, revocarea nu vă oferă o cheie de înlocuire. Revocați accesul doar atunci când intenționați să opriți accesul API (de exemplu, o cheie compromisă pe care nu o puteți înlocui imediat).

cURL

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

JavaScript

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

Python

import requests

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

Răspuns

{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Dacă contul nu are nicio cheie de revocat, răspunsul este 404.

Chei cu domeniu limitat #

O cheie cu domeniu limitat este o cheie API suplimentară pe care o creați pentru o sarcină specifică, având doar accesul de care acea sarcină are nevoie. Cazul clasic: doriți să conectați un tablou de bord pentru clienți, un instrument de raportare sau un script intern la contul dvs. fără a oferi o cheie care ar putea, de asemenea, să trimită mesaje, să modifice agenții AI sau să cumpere un număr de telefon.

Restricția însoțește cheia însăși, astfel încât oricine o deține poate face doar ceea ce ați permis în momentul creării acesteia.

Ce puteți restricționa

De asemenea, puteți oferi unei chei o dată de expires_at (ISO 8601, și trebuie să fie în viitor). După acel moment, cheia nu mai funcționează de la sine. Lăsați acest câmp necompletat și cheia nu va expira niciodată până când nu o revocați.

Refuzurile sunt implicite. Dacă o cerere depășește ceea ce permite cheia, aceasta este refuzată în loc să fie permisă: o scriere cu o cheie de tip „doar citire” returnează 403 cu error_code: "key_read_only", iar orice acțiune în afara secțiunilor permise ale cheii returnează 403 cu error_code: "key_scope_denied". Dacă o cheie cu domeniu limitat primește un 403 neașteptat, endpoint-ul apelat pur și simplu nu se află în domeniul său de aplicare — extindeți domeniul cheii sau utilizați cheia principală.

Doar proprietarul contului gestionează cheile. Aceste patru endpoint-uri necesită cheia principală sau o sesiune de proprietar în aplicație. O cheie cu domeniu limitat nu poate niciodată să listeze, creeze, editeze sau revoce chei — inclusiv pe ea însăși — deci o cheie restricționată nu poate fi niciodată utilizată pentru a crea una cu permisiuni mai largi. Încercarea returnează 403 cu error_code: "key_scope_denied". Din același motiv, API Keys nu este o secțiune pe care o puteți acorda: solicitarea acesteia returnează 400 cu error_code: "invalid_scopes".

Listarea cheilor cu domeniu limitat #

Returnează cheile cu domeniu limitat ale contului, cele mai noi primele (până la 200), inclusiv cele revocate, astfel încât să puteți vedea ce a fost retras și când. Sunt returnate doar previzualizările mascate — valoarea unei chei cu domeniu limitat este afișată o singură dată, la creare, și nu mai poate fi recuperată ulterior.

GET /api-keys

cURL

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

Răspuns

{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}

Crearea unei chei cu domeniu limitat #

Creează o cheie nouă cu domeniu de aplicare (scoped key) și returnează valoarea acesteia o singură dată.

POST /api-keys

Cheia este afișată o singură dată. Aceasta apare în acest răspuns și nicăieri altundeva, vreodată — nu există nicio modalitate de a o recupera ulterior. Stocați-o în momentul în care o primiți. Dacă o pierdeți, revocați-o și creați una nouă.

Câmpuri în corp (Body fields) — toate opționale:

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Răspuns — 201 Created

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}

Câteva detalii care merită cunoscute atunci când construiți pe baza acestora:

• Omiterea scopes nu este același lucru cu trimiterea unei liste tags goale. Omiteți scopes complet și veți obține setarea implicită sigură (doar citire, doar Analytics). Trimiteți "tags": [] în mod intenționat și cheia va putea utiliza fiecare secțiune — acest lucru este interpretat ca o cerere deliberată pentru o cheie fără restricții.
• read_only rămâne true dacă nu trimiteți în mod explicit false. O greșeală de scriere sau un flag lipsă nu pot produce niciodată accidental o cheie care poate scrie.

Actualizarea unei chei cu domeniu de aplicare #

Modifică eticheta, domeniile de aplicare și/sau data de expirare a unei chei. Trimiteți orice combinație a celor trei; dacă nu trimiteți niciuna, se returnează 400.

PATCH /api-keys/{id}

{id} reprezintă id cheii din listă (valoarea key_...), niciodată cheia în sine.

Domeniile de aplicare sunt înlocuite, nu îmbinate. Tot ceea ce trimiteți devine setul complet de permisiuni al cheii. Acest lucru este deliberat: restrângerea unei chei nu poate lăsa niciodată în mod silențios accesul vechi, mai larg, activ. Trimiteți întotdeauna obiectul scopes complet pe care îl doriți, nu doar câmpul pe care îl modificați.

Valoarea cheii nu se schimbă niciodată. Nu există o funcție de rotire pe loc pentru o cheie cu domeniu de aplicare — pentru a o reînnoi, creați o cheie nouă și revocați-o pe cea veche, astfel încât accesul unei credențiale să nu se poată schimba niciodată în cadrul unei integrări care încă o deține.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'

Răspuns

{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}

Dacă nu există nicio cheie cu acel id în contul dumneavoastră, răspunsul este 404.

Revocarea unei chei cu domeniu de aplicare (scoped key) #

Revocarea este imediată: următoarea cerere care utilizează acea cheie va fi respinsă cu un 401. Cheia principală și toate celelalte chei cu domeniu de aplicare rămân neafectate.

DELETE /api-keys/{id}

Cheia rămâne în listă marcată ca "revoked": true, astfel încât să păstrați evidența a ceea ce a existat și la ce avea acces. Revocarea unei chei care este deja revocată reușește și nu schimbă nimic.

cURL

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

Răspuns

{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Erori API pentru cheile API #

Endpoint-urile pentru chei API returnează plicul de eroare standard:

{
  "success": false,
  "error": "No API key found for this account"
}

Pe un endpoint de cheie API, o cheie lipsă sau invalidă returnează 401, iar un cont fără o cheie înregistrată returnează 404. Codurile partajate pe care le poate returna orice endpoint — 400, 403 (planul tău nu include acces API), 429 (limită de rată) și 500 — sunt listate împreună cu instrucțiuni de reîncercare în Erori și paginare.

Endpoint-urile pentru cheile cu domeniu de aplicare adaugă câteva coduri denumite în câmpul error_code, astfel încât să puteți distinge cazurile:

Pașii următori #

• Autentificare — cele patru metode de autentificare a unei cereri și modul în care sunt aplicate domeniile de aplicare ale cheilor.
• Erori și limite de rată — coduri de stare și limita de 300 cereri/min.