API-nøgler og scopes

Hver anmodning til Sursas API sendes med en API-nøgle fra din organisation. En nøgle tilhører organisationen, ikke en person: Den bliver ved med at virke, når den medarbejder, der oprettede den, stopper, og hvad den kan, er indstillet på selve nøglen.

Hvad en nøgle har lov til

Tre indstillinger på en nøgle bestemmer, hvad en anmodning med den kan se og ændre. Hver af dem kan kun indsnævre de andre.

Indstilling	Hvad den styrer
Role (rolle)	`admin`, `editor`, `verifier` eller `viewer`, de samme roller, som personer har. Nøglen kan det samme som en bruger med den rolle.
Scopes	Hvilke dele af API’et nøglen må kalde, fx `cards:read` eller `webhooks:manage`. Se Scopes for nøgler.
Data profile (dataprofil)	Valgfri. Begrænser nøglen til de kategorier af viden, som profilen tillader, ligesom en bruger med den profil.

En nøgle kan også begrænses til bestemte samlinger og få en udløbsdato. En anmodning uden for disse grænser mislykkes: Et manglende scope returnerer 403 med koden api_keys.scope, og et objekt, som nøglen ikke kan se, returnerer 404, præcis som om det ikke fandtes.

Giv hver integration sin egen nøgle med den snævreste rolle og de snævreste scopes, den har brug for. Et synkroniseringsjob, der kun skriver dokumenter, behøver ikke admin; et rapporteringsjob behøver ingen scopes til skrivning.

Opret en nøgle

En administrator i organisationen opretter nøgler i Sursa under Administration → API keys (administration, API-nøgler) eller med POST /v1/api-keys med en nøgle eller session, der 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 indeholder nøglens værdi i key. Den vises én gang: Sursa gemmer kun en hash af den og kan ikke vise den igen. En nøgle ser ud som kb_ efterfulgt af 43 tegn; de første tegn (prefix) vises i listen over nøgler, så du kan skelne nøglerne fra hinanden.

Uden scopes får nøglen sin rolles scopes. Angiv scopes for at indsnævre den yderligere. Uden expires_at udløber nøglen ikke.

Hold nøgler hemmelige

Gem nøgler i et hemmelighedslager eller i din tjenestes miljøvariabler, aldrig i kildekoden.
Brug kun nøgler fra dine servere. Sursa accepterer anmodninger fra browsere (CORS er åben), men en nøgle på en webside er synlig for alle, der åbner den.
Send aldrig en nøgle i en URL. Send den kun i headeren Authorization.
Slipper en nøgle ud, så tilbagekald den straks, og opret en ny.

Kontrollér en nøgle

GET /v1/me returnerer nøglen, dens rolle, gældende scopes, dataprofil, udløb og hastighedsgrænse. Den virker med enhver gyldig nøgle uanset dens scopes, så brug den som din integrations forbindelsestest, og når du undersøger en 403.

Rotér en nøgle

Rotation erstatter en nøgle uden at standse integrationen. Den hurtigste måde er at rotere nøglen: POST /v1/api-keys/{key_id}/roll udsteder en ny værdi for den samme nøgle med den samme rolle, de samme scopes, samlinger og den samme udløbsdato. Den tidligere værdi virker fortsat i overlap_hours (som standard 24 timer, op til 168), så du kan udrulle den nye værdi i mellemtiden; POST /v1/api-keys/{key_id}/revoke-previous afslutter overlappet før tid.

Vil du i stedet erstatte en nøgle med en anden nøgle:

Opret en ny nøgle med samme rolle, scopes og dataprofil.
Udrul den nye nøgle i din integration.
Hold øje med den gamle nøgle under Administration → API keys (eller last_used i GET /v1/api-keys), indtil den ikke længere bruges.
Tilbagekald den gamle nøgle.

Sæt en udløbsdato på nøgler, og rotér dem inden den. Sursa advarer organisationens administratorer, før en nøgle udløber; en udløbet nøgle returnerer 401 med koden api_keys.expired.

Tilbagekald en nøgle

Tilbagekald en nøgle under Administration → API keys eller med DELETE /v1/api-keys/{key_id}. Tilbagekaldelsen træder i kraft inden for få sekunder på alle API-servere. Anmodninger med en tilbagekaldt nøgle returnerer 401 med koden auth.not_authenticated.

Nøgler til en brugerdefineret kilde

En brugerdefineret kilde har sin egen slags nøgle. Den begynder med kbsrc_, den kan kun skrive dokumenter i netop den kilde, og den kan hverken læse eller søge i noget. Det er den sikreste nøgle at give en integrationsplatform som Zapier. Opret den på kildens side under API keys eller med POST /v1/sources/{source_id}/push-keys.

Når nøgler ikke er tilgængelige

API-nøgler er en del af organisationens prisplan. Omfatter prisplanen dem ikke, returnerer både oprettelsen af en nøgle og alle anmodninger med en nøgle 403 med koden api_keys.feature_disabled.