Garanti

Skrivebeskyttet tilgang

Et token utstedt med scope=read leser, og gjør ingenting annet. Ikke som en konvensjon: enhver metode som ikke er et lesekall, avvises med 403 Forbidden før forespørselen når endepunktet — avgjort av tokenets scope og HTTP-metoden alene.

Det er dette som gjør et token med lese-scope trygt å gi en eksportjobb, et dashbord, en BI-jobb eller en overvåkingssonde: ingen trenger å lese kildekoden til mottakersystemet for å vite at det ikke kan endre noe i kundens Visena-instans. Denne siden er demonstrasjonen framfor forsikringen — samme token, nektet å skrive, med forespørselen som ble sendt og svarkroppen som kom tilbake.

Slik skaffer du et, i tre trekk

1. Opprett en API-tilgang — i kundens Visena-instans, eller be administratoren deres om paret. Gjennomgangen i Legitimasjon og tokener viser det i grensesnittet, skjerm for skjerm.
2. Be om lese-scopet — be om tokenet med scope=read og ingenting mer. Scope er obligatorisk og aldri underforstått: en tokenforespørsel uten scope avvises med 400 invalid_scope i stedet for stille å falle tilbake på alt tilgangen har. Hver utstedelse er derfor et uttrykt valg.
3. Send det som et bearer-token — Authorization: Bearer … på hvert kall. Ingenting annet endres: samme endepunkter, samme JSON, samme paginering.

curl -X POST https://api.visena.example/acme/auth/api/v1/token \
  -u "acme-partner-3f9a:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=read"

# 200 OK
{
  "access_token": "dcrEUVpMEpYqbdsDKawBb1yTqIAELMgqIO4KrN…",
  "scope": "read",
  "token_type": "Bearer",
  "expires_in": 86399
}

Bytt verten med den base-URL-en du fikk ved oppstart, og acme med kundens instansnavn.

To tak, ikke ett

Scopet du ber om, er det nederste taket: det du holder smalt per jobb, og det denne siden handler om. Over det ligger tilgangens eget tak — settet av scoper tilgangen i det hele tatt er registrert for. Administratoren velger det når tilgangen opprettes, og det kan ikke endres etterpå.

Forskjellen betyr noe når du blir spurt om hva en integrasjon kan gjøre, ikke bare hva den gjør. En tilgang opprettet som «les og skriv» er skrivebeskyttet så lenge jobbene dine ber om read — men den samme legitimasjonen kan utstede et skrivetoken. En tilgang opprettet som «bare lesing» kan ikke det: forespørselen om write faller utenfor det registrerte settet og avvises av autorisasjonstjeneren, uansett hvem som ber og hvilken jobb som ber. Det er den formen å be kundens administrator om når integrasjonen aldri skal skrive.

Begge tak gjelder samtidig, og det smaleste vinner. Denne siden viser det nederste i arbeid; det øverste flytter bare hvor tidlig et skrivekall stopper — ved utstedelsen i stedet for ved forespørselen.

Hva lese-scopet utelukker

Regelen handler om forespørselens HTTP-metode, ikke om hva endepunktet bak den gjør. De trygge metodene — GET, HEAD og OPTIONS — krever read. Alle andre metoder krever write. Ingenting annet er med i avgjørelsen: ikke stien, ikke forespørselskroppen, ikke brukeren bak tilgangen.

Sjekken skjer i et filter, etter at bearer-tokenet er validert og før forespørselen når endepunktet — før kroppen tolkes, før feltvalidering, og før noen brukerkontekst er etablert.

Hver leseoperasjon i Partner API er en GET — å hente én post, offset- og markørlistene, endringsfeedene på /timeline og duplikatsøket på /duplicates like fullt — så et read-token når hele leseflaten, og metoderegelen fanger ingenting en leser trenger. Men det er fortsatt metoden som avgjør, ikke hensikten: et søk som tok kriteriene sine i en POST-kropp, ville også blitt avvist.

Bevis: samme token, nektet å skrive

Her er håndhevingen framfor løftet. Tokenet nedenfor er det som nettopp leste en person; nå forsøker det en PUT mot samme person. Utvekslingen er et virkelig opptak, mot en utviklingsinstans som heter visena, med lokalsegmentet no — bytt inn kundens instansnavn og det lokalsegmentet du kaller med.

PUT https://api.visena.example/visena/api/v1/no/person/KDiJs47rD4THRo5uPwlESr0
Authorization: Bearer <access_token>   ← minted with scope=read
Content-Type: application/json

{
  "firstName": "Karri",
  "lastName": "Nordmann",
  "initials": "KN",
  "jobTitle": "Principal Advisor",
  "primaryEmail": "kari.nordmann@example.com",
  "mobilePhone": "+4740000000",
  "countryCode": "NO",
  "isActive": true
}

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "timestamp": "2026-08-19T11:19:16.241Z",
  "status": 403,
  "type": "about:blank",
  "errorType": "GENERIC",
  "title": "Forbidden",
  "detail": "Et unntak oppstod under autentisering",
  "instance": "/visena/api/v1/no/person/KDiJs47rD4THRo5uPwlESr0"
}

Kroppen er et problemdokument etter RFC 9457, levert som application/problem+json — formen hver feil i Partner API bruker, beskrevet i Feil og feilsøking. type er about:blank, som i RFC 9457 betyr at statuskoden bærer hele betydningen, og title er statuskodens begrunnelsestekst. Det du skal handle på i kode, og det du skal vise en revisor, er altså 403 på en skriving: se på statuskoden, ikke på detail-teksten, som er en generell plattformmelding og ikke navngir scopet.

Skrivingen avvises før den når dataene. Forespørselen kommer aldri til endepunktet, så det finnes ingen delvis endring å finne og ingenting å rulle tilbake.

Når du bør bruke det

• Eksporter, dashbord og BI — alt som har som oppgave å forlate Visena slik det fant det.
• Første milepæl i en integrasjon — få lesingen riktig ende til ende, og utvid scopet når du faktisk begynner å skrive.
• Tredjeparter og konsulenter — et token som ikke kan skrive, er en mye kortere samtale enn et som kan.
• Overvåking og avstemming — sammenlign Visena med et annet system uten noen mulighet for å «fikse» det ved et uhell.

Trenger en jobb begge, utsted to tokener fra samme tilgang — read for lesestien, read write for skrivestien — framfor å gi hele jobben skrivetilgang. Det er to separate utstedelser fra samme par, så det koster én ekstra tokenforespørsel og ingen ekstra tilgang.

Feil og feilsøking dekker resten av problemdokumentene du vil møte, og Sette i produksjon er sjekklisten for dagen den skrivebeskyttede milepælen er nådd og du begynner å skrive.