API-võtmed ja ulatused

Iga Sursa API päring tehakse teie organisatsiooni API-võtmega. Võti kuulub organisatsioonile, mitte inimesele: see töötab edasi ka siis, kui selle loonud töötaja lahkub, ja see, mida võti teha saab, on määratud võtmel endal.

Mida võtmel on lubatud teha

Kolm võtme seadet määravad, mida selle võtmega tehtud päring näha ja muuta saab. Iga seade ainult kitsendab teisi.

Seade	Mida see määrab
Role (roll)	`admin`, `editor`, `verifier` või `viewer`, samad rollid, mis on inimestel. Võti saab teha seda, mida selle rolliga kasutaja.
Scopes (ulatused)	Milliseid API osi võti võib kutsuda, näiteks `cards:read` või `webhooks:manage`. Vt Võtmete ulatused.
Data profile (andmeprofiil)	Valikuline. Piirab võtme nende teadmiste kategooriatega, mida profiil lubab, nagu selle profiiliga kasutaja puhul.

Võtme saab piirata ka mõne koguga ja sellele saab määrata aegumiskuupäeva. Nendest piiridest väljuv päring ebaõnnestub: puuduv ulatus tagastab 403 koodiga api_keys.scope ja objekt, mida võti ei näe, tagastab 404 täpselt nii, nagu seda ei oleks olemas.

Andke igale integratsioonile oma võti, millel on kitsaim vajalik roll ja ulatused. Sünkroonimistöö, mis ainult kirjutab dokumente, ei vaja rolli admin; aruandlustöö ei vaja kirjutamisulatusi.

Võtme loomine

Organisatsiooni administraator loob võtmed Sursas jaotises Administration → API keys (haldus → API-võtmed) või päringuga POST /v1/api-keys, kasutades võtit või seanssi, millel on roll 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"
  }'

Vastus sisaldab võtme väärtust väljal key. Seda näidatakse üks kord: Sursa säilitab sellest ainult räsi ega saa seda uuesti näidata. Võti algab eesliitega kb_, millele järgneb 43 märki; esimesed märgid (prefix) kuvatakse võtmete loendis, et saaksite võtmeid eristada.

Ilma väljata scopes saab võti oma rolli ulatused. Edastage scopes, et võtit veelgi kitsendada. Ilma väljata expires_at võti ei aegu.

Võtmete salajas hoidmine

Hoidke võtmeid saladuste halduris või oma teenuse keskkonnamuutujates, mitte kunagi lähtekoodis.
Kasutage võtmeid ainult oma serveritest. Sursa võtab vastu päringuid brauseritest (CORS on avatud), kuid veebilehel olev võti on nähtav kõigile, kes lehe avavad.
Ärge kunagi saatke võtit URL-is. Saatke seda ainult päises Authorization.
Kui võti lekib, tühistage see kohe ja looge uus.

Võtme kontrollimine

GET /v1/me tagastab võtme, selle rolli, tegelikud ulatused, andmeprofiili, aegumise ja sageduspiirangu. See töötab iga kehtiva võtmega, olenemata selle ulatustest, seega kasutage seda oma integratsiooni ühendustestina ja vastuse 403 põhjuse uurimisel.

Võtme uuendamine

Uuendamine asendab võtme integratsiooni peatamata. Kiireim viis on anda võtmele uus väärtus: POST /v1/api-keys/{key_id}/roll väljastab samale võtmele uue väärtuse sama rolli, ulatuste, kogude ja aegumisega. Eelmine väärtus kehtib edasi parameetris overlap_hours antud aja (vaikimisi 24 tundi, kuni 168), nii et saate vahepeal uue väärtuse kasutusele võtta; POST /v1/api-keys/{key_id}/revoke-previous lõpetab kattuvusaja varem.

Võtme asendamiseks hoopis teise võtmega:

Looge uus võti sama rolli, ulatuste ja andmeprofiiliga.
Paigaldage uus võti oma integratsiooni.
Jälgige vana võtit jaotises Administration → API keys (või välja last_used päringus GET /v1/api-keys), kuni seda enam ei kasutata.
Tühistage vana võti.

Määrake võtmetele aegumiskuupäev ja uuendage neid enne selle saabumist. Sursa hoiatab organisatsiooni administraatoreid enne võtme aegumist; võti, mille kehtivus on lõppenud, tagastab 401 koodiga api_keys.expired.

Võtme tühistamine

Tühistage võti jaotises Administration → API keys või päringuga DELETE /v1/api-keys/{key_id}. Tühistamine jõustub mõne sekundi jooksul igas API-serveris. Tühistatud võtmega päringud tagastavad 401 koodiga auth.not_authenticated.

Kohandatud allika võtmed

Kohandatud allikal on oma võtmeliik. See algab eesliitega kbsrc_, saab kirjutada dokumente ainult sellesse ühte allikasse ega saa midagi lugeda ega otsida. See on kõige turvalisem võti, mida anda integratsiooniplatvormile, näiteks Zapierile. Looge see allika lehel jaotises API keys või päringuga POST /v1/sources/{source_id}/push-keys.

Kui võtmed ei ole saadaval

API-võtmed on osa organisatsiooni paketist. Kui pakett neid ei sisalda, tagastavad nii võtme loomine kui ka iga võtmega tehtud päring 403 koodiga api_keys.feature_disabled.