Autentifikacija ir raktai

Bearer raktas

Kiekviena užklausa turi antraštę Authorization su Bearer schema. Rakto nereikia tik GET / ir GET /openapi.json:

Authorization: Bearer dk_live_...

Taisyklės, kurios saugo jūsų raktą:

• Priimama tik Authorization: Bearer. Antraštė X-API-Key nepriimama, nes ji nutekėtų per peradresavimus.
• Raktas negali būti URL. Jei jis yra užklausos eilutėje (api_key, key, token, access_token), API grąžina 400 api_key_in_query. Tokį raktą laikykite nutekėjusiu ir jį rotuokite.
• Raktas nenaudojamas naršyklėje. API negrąžina Access-Control-* antraščių, o OPTIONS užklausa gauna 405. Raktą visada naudokite iš savo serverio.

Rakto formatas

Raktas atrodo taip: dk_live_ ir 49 simboliai [0-9A-Za-z], iš viso 57 simboliai.

Reguliarioji išraiška: ^dk_live_[0-9A-Za-z]{49}$. Kontrolinė suma leidžia atmesti rašybos klaidą ir aptikti raktą kode be tinklo užklausos. Priešdėlis dk_test_ rezervuotas ateičiai; smėlio dėžės v1 nėra.

Diko saugo tik rakto SHA-256 maišą ir užuominą (dk_live_Ab12…9xYz). Pats raktas niekada nerašomas į žurnalus, el. laiškus ar klaidų atsakymus.

Raktų kūrimas

Raktus kuriate Diko programėlėje, skiltyje Nustatymai → API, adresu /settings/api. Senoji nuoroda /kurejams vis dar veikia ir nukreipia čia. Forma prašo:

Sukūrus raktas parodomas vieną kartą. Kol nepažymėsite langelio Išsaugojau raktą saugioje vietoje, programėlė neleis uždaryti lango. Kūrimui, rotacijai, įjungimui ir IP sąrašo keitimui programėlė gali paprašyti pakartotinio patvirtinimo (galioja 10 minučių). Atšaukimas, išjungimas ir pervadinimas patvirtinimo nereikalauja, kad saugūs veiksmai būtų greiti.

Ribos: daugiausia 25 raktai (aktyvūs ir išjungti kartu). Pasibaigę, atšaukti ir rotacijos persidengimo metu veikiantys seni raktai neskaičiuojami. Per valandą galima sukurti ar rotuoti daugiausia 10 raktų.

Rakto objektas

GET /me grąžina raktą, kuriuo pateikta užklausa. Pats raktas, žinoma, neparodomas:

{
  "id": "key_4Vf9771zpS8JcQdtUcR0u8",
  "object": "api_key",
  "name": "CRM sync",
  "description": "",
  "hint": "dk_live_Ab12…9xYz",
  "scopes": ["meetings:read", "library:read"],
  "status": "active",
  "allowed_cidrs": [],
  "created_at": "2026-10-11T09:00:00.000Z",
  "expires_at": "2027-01-09T09:00:00.000Z",
  "last_used_at": null,
  "last_used_ip": null,
  "first_used_at": null,
  "disabled_at": null,
  "revoked_at": null,
  "revoked_reason": null,
  "rotated_from": null,
  "grace_until": null
}

Likusi GET /me atsakymo dalis taip pat laikosi mažiausių privilegijų principo. Todėl trečiajai šaliai perduotas raktas neatskleidžia paskyros savininko duomenų. user.email visada paslėptas (j***@example.com). credits yra null, nebent raktas turi leidimą library:write, vienintelį, kuris naudoja kreditus.

Būsenos

revoked_reason reikšmės: user (atšaukėte jūs), rotated (pasibaigė rotacijos persidengimas), admin (atšaukė komandos administratorius), owner (atšaukė komandos savininkas), user_disabled (paskyra išjungta), leaked (aptiktas nutekėjimas), dormant (ilgai nenaudotas), revoke_all (veiksmas Atšaukti visus raktus).

Galiojimas, priminimai ir nenaudojami raktai

• Likus 7 ir 1 dienai iki galiojimo pabaigos Diko išsiunčia el. laišką (tik jei galiojimas buvo bent 14 ir bent 2 dienų).
• Programėlė žymi raktą „Nenaudojamas“, jei jis nenaudotas 90 dienų. Raktas, nenaudotas 365 dienas, atšaukiamas automatiškai (dormant).
• Kiekvienas raktas turi last_used_at ir naudojimo statistiką programėlėje, todėl pamirštas integracijas lengva pastebėti ir atšaukti. last_used_at atnaujinamas ne dažniau kaip kas 5 minutes, todėl jis gali atsilikti nuo tikro paskutinio kreipinio.

Rotacija

Rotacija sukuria naują raktą ir leidžia senam dar kurį laiką veikti, kad spėtumėte atnaujinti sistemas be prastovos.

• Persidengimas: iškart, 1 val., 24 val. (numatytasis) arba 7 d.
• Naujas raktas paveldi pavadinimą, aprašą, leidimus ir IP sąrašą. Jis gauna tokią pat galiojimo trukmę kaip senasis (daugiausia 365 dienas), skaičiuojamą nuo rotacijos momento.
• Senas raktas gauna grace_until ir tampa revoked (rotated), kai laikas baigiasi.
• Vienu metu galima turėti tik vieną atvirą to paties rakto rotaciją.

Žingsnis po žingsnio receptas yra Saugumo gairėse.

Importai, kai raktas nustoja veikti

Importas, sukurtas per POST /library/imports, gali trukti kelias minutes. Kai jį sukūręs raktas nustoja veikti, Diko sustabdo ir importą. Todėl nutekėjęs raktas negali toliau eikvoti kreditų per jau eilėje esančius darbus.

• Šie veiksmai atšaukia rakto importus, kurie dar queued arba processing: rakto atšaukimas (jūsų, komandos administratoriaus ar savininko, veiksmas Atšaukti visus raktus arba automatiškai po GitHub pranešimo apie nutekėjimą), išjungimas, ištrynimas, rotacija su persidengimu iškart ir paskyros išjungimas. Paskyros API prieigos sustabdymas atšaukia visų jos raktų importus.
• queued importas iškart tampa canceled. processing importas tampa canceling, o sustojus darbui baigiasi kaip canceled. Kiekvienas pabaigimas siunčia įvykį library.import.canceled.
• Rotacija su persidengimu (1 val., 24 val. arba 7 d.) importų nesustabdo. Senam raktui tapus revoked (rotated) pasibaigus persidengimui, importai taip pat neatšaukiami. Jei seną raktą atšaukiate patys persidengimo metu, jo importai atšaukiami kaip bet kurio atšaukto rakto.
• Jau atliktas darbas apmokestinamas kaip įprasta: transkriptas, kuris jau buvo gautas arba baigiamas, vis tiek patenka į jūsų biblioteką.

Planas

API prieinamas „Verslas“ plane. API atsakymuose planas žymimas reikšme verslas. Klaida plan_required nurodo jį lauke required_plans.

GET /me rodo dabartinę būseną lauke access:

• access.plan yra asmeninis (asmeninis planas, kuris API neapima), verslas arba null, kai paskyra plano neturi;
• access.allowed nurodo, ar API užklausos leidžiamos;
• access.reason nurodo priežastį. Prieigą suteikia subscription (prenumerata), team (komandos planas), owner ir exempt (paskyros, kurios nemoka) arba paywall_off (apmokėjimas išjungtas). Prieigą atmeta subscription_required arba plan_required.

Planas tikrinamas kiekvienos užklausos metu, todėl raktai nepašalinami keičiant planą: jie vėl veikia, kai planas leidžia. GET /me plano netikrina, todėl tinka diagnostikai.

Autentifikacijos klaidos

401 atsakymai turi antraštę WWW-Authenticate: Bearer realm="diko", kai antraštės Authorization nėra, ir Bearer realm="diko", error="invalid_token" kitais atvejais.

Raktą atšaukus, išjungus ar rotavus, pakeitimas pasiekia API maždaug per 10 sekundžių.