API atslēgas un tvērumi

Katrs Sursa API pieprasījums tiek veikts ar jūsu organizācijas API atslēgu. Atslēga pieder organizācijai, nevis cilvēkam: tā turpina darboties, kad darbinieks, kas to izveidoja, aiziet, un tas, ko tā drīkst darīt, ir iestatīts pašā atslēgā.

Ko atslēgai ir atļauts darīt

Trīs atslēgas iestatījumi nosaka, ko pieprasījums ar to var redzēt un mainīt. Katrs no tiem tikai sašaurina pārējos.

Iestatījums	Ko tas nosaka
Role (loma)	`admin`, `editor`, `verifier` vai `viewer` – tās pašas lomas, kas ir cilvēkiem. Atslēga var darīt to, ko var lietotājs ar šo lomu.
Scopes (tvērumi)	Kuras API daļas atslēga drīkst izsaukt, piemēram, `cards:read` vai `webhooks:manage`. Sk. Atslēgu tvērumi.
Data profile (datu profils)	Neobligāts. Ierobežo atslēgu ar tām zināšanu kategorijām, kuras atļauj profils, tāpat kā lietotāju ar šo profilu.

Atslēgu var arī ierobežot ar dažām kolekcijām un piešķirt tai derīguma termiņu. Pieprasījums ārpus šīm robežām neizdodas: ja trūkst tvēruma, tiek atgriezts 403 ar kodu api_keys.scope, bet pieprasījums pēc objekta, ko atslēga nevar redzēt, saņem 404 tieši tā, it kā objekts neeksistētu.

Piešķiriet katrai integrācijai savu atslēgu ar šaurāko vajadzīgo lomu un tvērumiem. Sinhronizācijas darbam, kas tikai raksta dokumentus, nav vajadzīgs admin; pārskatu darbam nav vajadzīgi rakstīšanas tvērumi.

Atslēgas izveide

Organizācijas administrators izveido atslēgas Sursā sadaļā Administration → API keys (administrēšana, API atslēgas) vai ar POST /v1/api-keys, izmantojot atslēgu vai sesiju ar lomu admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Atbildē atslēgas vērtība ir laukā key. Tā tiek parādīta vienreiz: Sursa glabā tikai tās jaucējvērtību (hash) un nevar to parādīt vēlreiz. Atslēga izskatās kā kb_ un aiz tā 43 rakstzīmes; pirmās rakstzīmes (prefix) ir redzamas atslēgu sarakstā, lai atslēgas varētu atšķirt.

Bez scopes atslēga saņem savas lomas tvērumus. Nododiet scopes, lai tos sašaurinātu vēl vairāk. Bez expires_at atslēgai nav derīguma termiņa.

Atslēgu glabāšana noslēpumā

Glabājiet atslēgas noslēpumu krātuvē vai sava pakalpojuma vides mainīgajos, nekad – pirmkodā.
Izmantojiet atslēgas tikai no saviem serveriem. Sursa pieņem pieprasījumus no pārlūkiem (CORS ir atvērts), taču atslēga tīmekļa lapā ir redzama ikvienam, kas lapu atver.
Nekad nesūtiet atslēgu URL adresē. Sūtiet to tikai galvenē Authorization.
Ja atslēga ir noplūdusi, nekavējoties atsauciet to un izveidojiet jaunu.

Atslēgas pārbaude

GET /v1/me atgriež atslēgu, tās lomu, faktiskos tvērumus, datu profilu, derīguma termiņu un pieprasījumu biežuma limitu. Operācija darbojas ar jebkuru derīgu atslēgu neatkarīgi no tās tvērumiem, tāpēc izmantojiet to kā savas integrācijas savienojuma testu un tad, kad izmeklējat 403.

Atslēgas rotācija

Rotācija aizstāj atslēgu, neapturot integrāciju. Ātrākais veids ir nomainīt atslēgu pret jaunu vērtību: POST /v1/api-keys/{key_id}/roll izsniedz tai pašai atslēgai jaunu vērtību ar to pašu lomu, tvērumiem, kolekcijām un derīguma termiņu. Iepriekšējā vērtība turpina darboties overlap_hours (pēc noklusējuma 24 stundas, līdz 168), tāpēc pa to laiku varat ieviest jauno vērtību; POST /v1/api-keys/{key_id}/revoke-previous pārklāšanos beidz agrāk.

Lai atslēgu aizstātu ar citu atslēgu:

Izveidojiet jaunu atslēgu ar to pašu lomu, tvērumiem un datu profilu.
Ieviesiet jauno atslēgu savā integrācijā.
Vērojiet veco atslēgu sadaļā Administration → API keys (vai last_used operācijā GET /v1/api-keys), līdz tā vairs netiek izmantota.
Atsauciet veco atslēgu.

Iestatiet atslēgām derīguma termiņu un nomainiet tās pirms tā beigām. Sursa brīdina organizācijas administratorus pirms atslēgas derīguma beigām; atslēga ar beigušos derīguma termiņu atgriež 401 ar kodu api_keys.expired.

Atslēgas atsaukšana

Atsauciet atslēgu sadaļā Administration → API keys vai ar DELETE /v1/api-keys/{key_id}. Atsaukšana dažu sekunžu laikā stājas spēkā visos API serveros. Pieprasījumi ar atsauktu atslēgu atgriež 401 ar kodu auth.not_authenticated.

Pielāgota avota atslēgas

Pielāgotam avotam ir savs atslēgu veids. Šāda atslēga sākas ar kbsrc_, tā var tikai rakstīt dokumentus šajā vienā avotā un nevar neko lasīt vai meklēt. Tā ir drošākā atslēga, ko dot integrāciju platformai, piemēram, Zapier. Izveidojiet to avota lapā daļā API keys vai ar POST /v1/sources/{source_id}/push-keys.

Kad atslēgas nav pieejamas

API atslēgas ir daļa no organizācijas plāna. Ja plānā tās nav iekļautas, atslēgas izveide un katrs pieprasījums ar atslēgu atgriež 403 ar kodu api_keys.feature_disabled.