API-nycklar och omfång

Varje anrop till Sursa API görs med en API-nyckel som tillhör din organisation. En nyckel tillhör organisationen, inte en person: den fortsätter att fungera när medarbetaren som skapade den slutar, och vad den får göra ställs in på själva nyckeln.

Vad en nyckel får göra

Tre inställningar på en nyckel avgör vad ett anrop med den kan se och ändra. Var och en kan bara snäva in de andra.

Inställning	Vad den styr
Roll	`admin`, `editor`, `verifier` eller `viewer`, samma roller som personer har. Nyckeln kan göra det som en användare med den rollen kan göra.
Omfång	Vilka delar av API:et som nyckeln får anropa, till exempel `cards:read` eller `webhooks:manage`. Se Nycklarnas omfång.
Dataprofil	Valfri. Begränsar nyckeln till de kunskapskategorier som profilen tillåter, som en användare med den profilen.

En nyckel kan också begränsas till vissa samlingar och få ett utgångsdatum. Ett anrop utanför de här gränserna misslyckas: ett omfång som saknas returnerar 403 med koden api_keys.scope, och ett objekt som nyckeln inte kan se returnerar 404, precis som om det inte fanns.

Ge varje integration en egen nyckel med den snävaste roll och de snävaste omfång som den behöver. Ett synkningsjobb som bara skriver dokument behöver inte admin; ett rapportjobb behöver inga skrivomfång.

Skapa en nyckel

En administratör i organisationen skapar nycklar i Sursa under Administration → API keys, eller med POST /v1/api-keys med en nyckel eller session 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 innehåller nyckelns värde i key. Det visas en gång: Sursa sparar bara en hash av det och kan inte visa det igen. En nyckel ser ut som kb_ följt av 43 tecken; de första tecknen (prefix) visas i listan över nycklar, så att du kan skilja nycklarna åt.

Utan scopes får nyckeln sin rolls omfång. Skicka scopes för att snäva in den ytterligare. Utan expires_at upphör nyckeln inte att gälla.

Håll nycklarna hemliga

Lagra nycklar i en hemlighetshanterare eller i miljövariabler för din tjänst, aldrig i källkoden.
Använd nycklar bara från dina servrar. Sursa tar emot anrop från webbläsare (CORS är öppet), men en nyckel på en webbsida syns för alla som öppnar den.
Skicka aldrig en nyckel i en URL. Skicka den bara i huvudet Authorization.
Om en nyckel läcker ut återkallar du den genast och skapar en ny.

Kontrollera en nyckel

GET /v1/me returnerar nyckeln, dess roll, faktiska omfång, dataprofil, utgångsdatum och hastighetsbegränsning. Den fungerar med alla giltiga nycklar, oavsett omfång, så använd den som anslutningstest för din integration och när du undersöker en 403.

Rotera en nyckel

Rotation ersätter en nyckel utan att integrationen stoppas. Det snabbaste sättet är att rotera nyckeln: POST /v1/api-keys/{key_id}/roll utfärdar ett nytt värde för samma nyckel, med samma roll, omfång, samlingar och utgångsdatum. Det tidigare värdet fortsätter att fungera i overlap_hours (24 timmar som standard, upp till 168), så att du hinner driftsätta det nya värdet under tiden; POST /v1/api-keys/{key_id}/revoke-previous avslutar överlappningen tidigare.

Om du i stället vill ersätta en nyckel med en annan nyckel:

Skapa en ny nyckel med samma roll, omfång och dataprofil.
Driftsätt den nya nyckeln i din integration.
Följ den gamla nyckeln under Administration → API keys (eller last_used i GET /v1/api-keys) tills den inte längre används.
Återkalla den gamla nyckeln.

Ange ett utgångsdatum på nycklarna och rotera dem innan det infaller. Sursa varnar organisationens administratörer innan en nyckel upphör att gälla; en nyckel som har gått ut returnerar 401 med koden api_keys.expired.

Återkalla en nyckel

Återkalla en nyckel under Administration → API keys eller med DELETE /v1/api-keys/{key_id}. Återkallelsen får effekt inom några sekunder på varje API-server. Anrop med en återkallad nyckel returnerar 401 med koden auth.not_authenticated.

Nycklar för en egen källa

En egen källa har en egen typ av nyckel. Den börjar med kbsrc_, den kan bara skriva dokument till just den källan, och den kan inte läsa eller söka i någonting. Det är den säkraste nyckeln att ge en integrationsplattform som Zapier. Skapa den på källans sida under API keys eller med POST /v1/sources/{source_id}/push-keys.

När nycklar inte är tillgängliga

API-nycklar ingår i organisationens prisplan. Om prisplanen inte omfattar dem returnerar både skapandet av en nyckel och varje anrop med en nyckel 403 med koden api_keys.feature_disabled.