Salt la conținut
Sursa Developers

POST/v1/api-keys

Creează o cheie API

create_api_key

Autentificare

Trimiteți o cheie API în antetul Authorization: Authorization: Bearer <cheie>.

Parametri de antet

  • Idempotency-Keystring

    Cheie pentru reîncercarea sigură a unei scrieri: 1–255 de caractere ASCII imprimabile; se recomandă un UUID v4 pentru fiecare operație logică. O reîncercare cu aceeași cheie în decurs de 24 de ore nu execută din nou operația: returnează răspunsul salvat (status, antete și corp) cu antetul Idempotency-Replayed: true. Aceeași cheie cu altă metodă, altă cale, alt Content-Type sau alt corp returnează 409 api.idempotency_mismatch; cât timp prima cerere încă rulează – 409 api.idempotency_in_progress cu Retry-After: 1. După un răspuns 5xx sau 429, cheia este eliberată, iar o reîncercare execută din nou operația. Cheia este valabilă în cadrul organizației și al apelantului (cheie API, utilizator sau cheie de sursă personalizată).

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    Doar pentru cheile API cu rolul admin. Execută cererea cu profilul de date <profile>[:viewer|verifier|editor], de exemplu employee:viewer. Cheia de instalare nu poate folosi acest antet (403).

Parametri cookie

  • kb_view_asstring

    Cookie-ul modului „View as” (vizualizare ca alt utilizator) pentru o sesiune. POST /auth/view-as îl setează, iar DELETE /auth/view-as îl șterge.

Corpul cererii

application/json

Obiect: ApiKeyCreate

  • namestringobligatoriu

    length ≥ 1, length ≤ 64

  • rolestring

    Implicit: "editor"

  • data_profilestring | null

    Profilul de date al cheii. Fără el, cheia primește profilul implicit al organizației. Profilul de date nu se aplică rolului admin. O cheie de administrator vede toate datele organizației, iar un profil diferit de full returnează 400 api_keys.data_profile_not_applicable.

  • expires_atstring (date-time) | null

    Momentul expirării cheii (ISO 8601, în viitor). null sau lipsa valorii înseamnă că cheia nu expiră.

  • scopesarray of ApiKeyScope | null

    Domeniile de acces ale cheii. Dacă lipsesc, domeniile urmează rolul: admin primește read, write, admin; editor și verifier primesc read, write; viewer primește read. Domeniul system este emis doar de administratorul instalării. Sunt acceptate și domeniile detaliate resource:action (ApiKeyScope); domeniile anterioare read, write și admin se extind în seturi de domenii.

  • collection_idsarray of integer | null

    Restrânge cheia la aceste colecții ale organizației. Fișele, căutarea, răspunsurile și evenimentele funcționează doar în ele, pe lângă rol și profilul de date. Lipsa valorii sau o listă goală înseamnă fără restricție. Dacă cheia care face cererea este ea însăși restrânsă la colecții, cheia nouă poate fi doar în colecțiile ei. Fără acest câmp, cheia nouă primește colecțiile cheii care face cererea. O listă goală sau o colecție din afara listei ei returnează 400 api_keys.invalid_collections.

    items ≤ 100

  • allowed_cidrsarray of string | null

    Rețelele din care poate fi folosită cheia, de exemplu 10.0.0.0/8 sau 2001:db8::/32. O singură adresă este o rețea cu o singură adresă. O cerere de la altă adresă returnează 403 api_keys.ip_not_allowed. Lipsa valorii înseamnă fără restricție.

    items ≤ 50

Răspunsuri

200Răspuns reușit

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

  • Idempotency-Replayed

    true înseamnă că răspunsul a fost redat din cel salvat pentru această cheie Idempotency-Key: operația nu a rulat din nou.

application/json

Obiect: ApiKeyCreated

  • idintegerobligatoriu
  • namestringobligatoriu
  • prefixstringobligatoriu
  • roleRoleobligatoriu
  • created_atstring (date-time)obligatoriu
  • keystringobligatoriu
  • data_profilestring | nullobligatoriu
  • expires_atstring (date-time)

    Momentul expirării. Prezent doar pentru cheile cu dată de expirare.

  • scopesarray of string

    Domeniile de acces explicite ale cheii. Prezent doar pentru cheile cu domenii setate explicit.

  • collection_idsarray of integer

    Restricția la colecții. Prezent doar pentru cheile cu restricție.

  • allowed_cidrsarray of string

    Rețelele permise. Prezent doar pentru cheile cu restricție.

400Cererea este invalidă: valoarea unui parametru sau starea obiectului nu permite acțiunea (`detail` este un mesaj).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

401Nu au fost trimise date de autentificare (nici cookie de sesiune, nici cheie API) sau cheia nu a fost găsită.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

403Acțiunea nu este permisă: rolul este insuficient, nu există acces la colecție sau la fișă, cererea rulează în modul „View as” (vizualizare ca alt utilizator) sau organizația este suspendată ori ștearsă (`detail` este un obiect cu `code: org_suspended | org_deleted`).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

422Eroare de validare: corpul sau parametrii nu corespund schemei (`detail` este o listă de erori de validare) ori valoarea unui parametru este în afara intervalului permis (`detail` este un mesaj).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

429Prea multe cereri (`api.rate_limited`), cota organizației pentru minut, zi sau lună este epuizată (`api.quota_exceeded`; `error.details` conține `quota`, `limit` și `reset_at`), limita organizației este atinsă sau serviciul de răspunsuri este ocupat (`answers.engine_busy`). Așteptați timpul indicat în antetul `Retry-After`.

Antetele răspunsului

  • Retry-After

    Numărul de secunde de așteptat înainte de a reîncerca cererea.

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

Coduri de eroare

Codurile pe care acest endpoint le poate returna în error.code, pe lângă codurile generale ale oricărei cereri.

Reîncercări sigure

Trimiteți un antet Idempotency-Key (de exemplu, un UUID) cu fiecare POST și PATCH. O reîncercare cu aceeași cheie în decurs de 24 de ore returnează răspunsul salvat, fără să execute din nou cererea.

Limite de frecvență

Răspunsurile conțin antetele RateLimit și RateLimit-Policy, precum și antetele anterioare X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset. Un răspuns 429 conține Retry-After în secunde: așteptați și reîncercați.

← api-keys · Referința API