REST UserAPI

Det ordinære REST-grensesnittet ligger under /api/ og krever OAuth 2.0-scope userapi. Bruk JSON med Content-Type: application/json. OpenAPI-referansen er den komplette kontrakten; tabellene her beskriver anbefalte kundearbeidsflyter. REST UserAPI er produksjonsgrensesnittet og er ikke omfattet av SCIMs beta-status.

Brukere

Ved oppretting anbefales en godkjent accessTemplateId. Hvis både departmentCode og externalDepartmentId sendes, har departmentCode prioritet. externalDepartmentId skal være én eksakt verdi.

Oppslag på e-post før oppretting

Integrasjoner bør slå opp eksisterende WebSak-brukere før de vurderer å kalle POST /api/Users:

GET /api/Users?email=person%40example.no&limit=100&offset=0

Filteret søker eksakt i aktive adresseposter. Innsendt og lagret verdi trimmes, og store/små bokstaver behandles likt. Det søkes ikke i de eldre Gid_EmailAdr-feltene. Både aktive og deaktiverte brukere kan returneres. E-post er ikke en unik nøkkel, så svaret kan inneholde flere brukere:

1. Ingen treff (200 OK med []): brukeren kan opprettes etter øvrige kontroller.
2. Ett treff: bruk eksisterende gidId, les loginmappingen med GET /api/Users/{gidId}/useraccesses, og oppdater den eksisterende brukeren ved behov.
3. Flere treff: stopp automatisk behandling og krev manuell avklaring.

Filteret anvendes før offset og limit. Integrasjonen må derfor lese alle sider før den konkluderer med at treffet er entydig dersom limit kan skjule flere treff. Sett includeEmailAddresses=true dersom aktive adresser også skal være med i responsen; selve filteret aktiverer ikke dette inkluderingsflagget. En tom eller blank email avvises med 400 Bad Request.

E-post er bare oppslagsgrunnlag og må ikke behandles som stabil identifikator, Entra object ID eller REST-feltet externalId. Oppslaget endrer heller ikke oppførselen til POST, PUT eller loginmapping-rutene: UserAPI kobler, oppdaterer eller blokkerer ikke ordinær brukeroppretting automatisk basert på resultatet av e-postsøket.

Sekundærbruker

Sekundærbrukere støttes via POST /api/Users. De kobles til én aktiv primærbruker ved å matche normalisert primær e-postadresse.

{
  "isSecondaryUser": true,
  "code": "SEK123",
  "name": "Eksempel Sekundær",
  "mailAddresses": ["person@example.no"],
  "departmentCode": "ADM-ENHET",
  "accessTemplateId": "<rettighetsmal-id>"
}

En sekundærbruker må ha minst én e-postadresse og kan ikke inneholde username eller userAccesses. Nøyaktig én aktiv primærbruker må ha samme e-post. Ingen treff gir 400; flere treff gir 409. Kunden må derfor rydde duplikate e-postadresser før provisjonering.

Avdelinger

Bruk V2-ruten /api/v2/departments. Aliaset /api/v2/departmentsv2 er deprecated.

Avdelingens externalId lagres i Gid_DIV1 og må være én eksakt ekstern ID. Ikke bruk pipe-separerte ID-er. Hvis flere eksterne organisasjonsenheter skal samles til én WebSak-avdeling, må mappingen gjøres i kildesystemet eller i et eksplisitt integrasjonslag før kallet til UserAPI.

Oppretting og vedlikehold har viktige regler for forelder, kortbetegnelse, fullstendig PUT og deaktivering. Følg den egne avdelingsguiden før integrasjonen settes i drift.

Roller og tilgangsfunksjoner

Roller beskriver lese-/skrivetilgang og organisatoriske avgrensninger. Tilgangsfunksjoner beskriver handlingene brukeren kan utføre. Bruk helst accessTemplateId ved oppretting og oppdatering, slik at et godkjent sett av roller og funksjoner tildeles samlet.

REST-referansen inneholder også ruter for å lese og vedlikeholde roller og tilgangskoder direkte. Direkte endringer krever mer kundespesifikk kontroll og bør bare brukes når malbasert tildeling ikke dekker behovet.

Se guiden for roller og tilgangsfunksjoner for forskjellen mellom rolle-ID, konkret roleId, access codes, rettighetsmal og loginmapping.

Tilgangsgrupper

Foretrekk ID-baserte ruter når klienten har gruppe-ID. Navn kan endres og er derfor en svakere korrelasjonsnøkkel.

Se guiden for tilgangsgrupper for gyldighet, idempotente medlemskapsendringer og begrensningene for saks- og journalgrupper.

Identiteter og soner

/api/Identities gjelder identitetskategorier 2 og 3, som kontakt- og organisasjonsidentiteter. Endepunktet oppretter ikke en WebSak-bruker og registrerer ikke loginmapping i IdentityServer. /api/Zones viser sonene som kan brukes i accessToZones.

Feil og idempotens

• Behandle 400/422 som valideringsfeil og rett payloaden.
• Behandle 409 fra brukeroppretting som signal om å hente eksisterende bruker.
• Gjenta ikke en POST ukritisk etter ukjent resultat; slå først opp med stabil nøkkel.
• Aktivering, deaktivering og medlemskapsendringer bør uttrykke ønsket tilstand.
• IdentityServer-operasjoner kan feile etter at WebSak er oppdatert. Les begge relevante visninger på nytt før retry.

Se legacy-oversikten for gamle GET-baserte mutasjoner som ikke skal tas i bruk av nye integrasjoner.