API-nøkler og scopes

Hver forespørsel til Sursas API gjøres med en API-nøkkel fra organisasjonen din. En nøkkel tilhører organisasjonen, ikke en person: Den fortsetter å virke når den ansatte som opprettet den, slutter, og hva den kan gjøre, angis på selve nøkkelen.

Hva en nøkkel har lov til

Tre innstillinger på en nøkkel avgjør hva en forespørsel med den kan se og endre. Hver av dem kan bare snevre inn de andre.

En nøkkel kan også begrenses til noen samlinger og få en utløpsdato. En forespørsel utenfor disse grensene mislykkes: Et manglende scope returnerer 403 med koden api_keys.scope, og et objekt som nøkkelen ikke kan se, returnerer 404, akkurat som om det ikke fantes.

Gi hver integrasjon sin egen nøkkel med den smaleste rollen og de færreste scopene den trenger. En synkroniseringsjobb som bare skriver dokumenter, trenger ikke admin; en rapporteringsjobb trenger ikke scopes for skriving.

Opprett en nøkkel

En administrator i organisasjonen oppretter nøkler i Sursa under Administration → API keys (administrasjon, API-nøkler) eller med POST /v1/api-keys og en nøkkel eller økt som har rollen 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"
  }'

Svaret inneholder verdien til nøkkelen i key. Den vises én gang: Sursa lagrer bare en hash av den og kan ikke vise den igjen. En nøkkel ser ut som kb_ etterfulgt av 43 tegn; de første tegnene (prefix) vises i listen over nøkler, slik at du kan skille nøklene fra hverandre.

Uten scopes får nøkkelen scopene til rollen sin. Send scopes for å snevre den inn ytterligere. Uten expires_at utløper ikke nøkkelen.

Hold nøklene hemmelige

• Lagre nøkler i et hemmelighetslager eller i miljøvariablene til tjenesten din, aldri i kildekoden.
• Bruk nøkler bare fra serverne dine. Sursa godtar forespørsler fra nettlesere (CORS er åpent), men en nøkkel på en nettside er synlig for alle som åpner den.
• Send aldri en nøkkel i en URL. Send den bare i headeren Authorization.
• Hvis en nøkkel lekker, trekker du den tilbake med en gang og oppretter en ny.

Kontroller en nøkkel

GET /v1/me returnerer nøkkelen, rollen, de gjeldende scopene, dataprofilen, utløpet og hastighetsgrensen. Den fungerer med alle gyldige nøkler, uansett scopes, så bruk den som tilkoblingstest for integrasjonen din og når du undersøker en 403.

Roter en nøkkel

Rotasjon erstatter en nøkkel uten å stoppe integrasjonen. Den raskeste måten er å rotere selve nøkkelen: POST /v1/api-keys/{key_id}/roll utsteder en ny verdi for den samme nøkkelen, med samme rolle, scopes, samlinger og utløpsdato. Den forrige verdien virker fortsatt i overlap_hours (24 timer som standard, opptil 168), så du kan ta i bruk den nye verdien i mellomtiden; POST /v1/api-keys/{key_id}/revoke-previous avslutter overlappet tidligere.

Slik erstatter du i stedet en nøkkel med en annen:

1. Opprett en ny nøkkel med samme rolle, scopes og dataprofil.
2. Ta i bruk den nye nøkkelen i integrasjonen din.
3. Følg med på den gamle nøkkelen under Administration → API keys (eller last_used i GET /v1/api-keys) til den ikke lenger brukes.
4. Trekk tilbake den gamle nøkkelen.

Sett en utløpsdato på nøklene, og roter dem før den. Sursa varsler organisasjonens administratorer før en nøkkel utløper; en utløpt nøkkel returnerer 401 med koden api_keys.expired.

Trekk tilbake en nøkkel

Trekk tilbake en nøkkel under Administration → API keys eller med DELETE /v1/api-keys/{key_id}. Tilbaketrekkingen trer i kraft i løpet av sekunder på alle API-servere. Forespørsler med en tilbaketrukket nøkkel returnerer 401 med koden auth.not_authenticated.

Nøkler for en egendefinert kilde

En egendefinert kilde har sin egen type nøkkel. Den begynner med kbsrc_, kan bare skrive dokumenter til denne ene kilden og kan ikke lese eller søke i noe. Det er den tryggeste nøkkelen å gi en integrasjonsplattform som Zapier. Opprett den på kildens side under API keys eller med POST /v1/sources/{source_id}/push-keys.

Når nøkler ikke er tilgjengelige

API-nøkler er en del av organisasjonens prisplan. Hvis prisplanen ikke omfatter dem, returnerer både opprettelsen av en nøkkel og alle forespørsler med en nøkkel 403 med koden api_keys.feature_disabled.