B2B-integrasjon (M2M)

Denne guiden er for Wenn Property-kunder som skal integrere API-et i en backend-tjeneste (server-til-server), uten en interaktiv brukerøkt. Vi bruker OAuth 2.0 Client Credentials — også kjent som M2M (machine-to-machine).

For interaktive applikasjoner der sluttbrukere logger inn, se Autentisering i stedet.

1. Opprett en API-klient

API-klienter administreres i Wenn Property-webappen:

1. Logg inn og åpne API-klienter-siden i administrasjonsområdet ditt.
2. Opprett en ny klient, gi den et navn (vises i revisjonslogger), og velg scopes (f.eks. manage:shares).
3. Lagre verdiene som vises — client_secret vises kun én gang ved opprettelse, og igjen kun når du eksplisitt roterer klienten. Når den er borte fra skjermen, kan ingen hente den igjen.

Hvis du ikke ser API-klienter-siden, er ikke funksjonen aktivert for kontoen din ennå. Send e-post til hei@wennproperty.no for å be om tilgang.

Hemmelighold

client_secret skal aldri committes til git, lagres i klartekst i konfigurasjonsfiler eller deles på Slack/e-post. Bruk en secret manager (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault eller tilsvarende). Hvis du mister hemmeligheten, roter klienten for å utstede en ny.

Når du oppretter en klient, får du:

Verdi	Beskrivelse
client_id	Offentlig identifikator for klienten. Logges på hver forespørsel for revisjon
client_secret	Hemmelig nøkkel. Vises kun én gang — lagre den umiddelbart i en secret manager
Scopes	Tilgangene som er tildelt klienten (typisk manage:shares for delingslenke-integrasjoner)

I tillegg trenger du disse faste verdiene for å hente et token:

Verdi	Beskrivelse
Token-endepunkt	https://auth.wennproperty.com/oauth/token
audience	https://connect.wennproperty.com

2. Hent et access token

Be om et token via OAuth 2.0 Client Credentials-flyten:

curl --request POST \
  --url https://auth.wennproperty.com/oauth/token \
  --header "content-type: application/json" \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "DIN_CLIENT_ID",
    "client_secret": "DIN_CLIENT_SECRET",
    "audience": "https://connect.wennproperty.com"
  }'

Svaret ser slik ut:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Tokenet er en signert JWT som blant annet inneholder:

Krav	Beskrivelse
sub	Settes til client_id for M2M-tokens
https://connect.wennproperty.com/tenant_id	Wenn Property-tenanten tokenet er bundet til
scope	Mellomrom-separert liste over tilganger
gty	client-credentials for M2M-tokens
exp	Utløpstidspunkt (Unix-tid)

3. Cache tokenet (påkrevd)

Du må cache access tokenet. Tokens er gyldige i ~24 timer, men token-forespørsler legger til ~200 ms latens per kall og token-endepunktet er rate-limit. Klienter som henter et nytt token per API-kall vil:

• Risikere rate-limiting på token-endepunktet
• Legge til unødvendig latens på hvert API-kall
• Bruke opp eventuelle token-kvoter

Mønster

1. Lagre access_token sammen med absolutt utløpstidspunkt (now + expires_in).
2. Forny proaktivt når du er innenfor en buffer på 5 minutter før utløp — ikke vent til tokenet faktisk er utløpt.
3. Dedupliser samtidige forespørsler slik at en stim av API-kall ikke utløser N parallelle /oauth/token-kall. Én pågående fornying skal deles av alle ventende.
4. In-memory er greit. Cache i prosessens minne. Du trenger ikke en delt cache med mindre du kjører mange kortlevde workers.

Pseudokode

let cachedToken: string | null = null;
let expiresAt = 0;
let pending: Promise<string> | null = null;

async function getToken(): Promise<string> {
  // Bruk cache hvis tokenet har > 5 min igjen
  if (cachedToken && Date.now() < expiresAt - 5 * 60 * 1000) {
    return cachedToken;
  }

  // Dedupliser samtidige fornyinger
  if (!pending) {
    pending = fetchNewToken().finally(() => { pending = null; });
  }
  return pending;
}

async function fetchNewToken(): Promise<string> {
  const res = await fetch(TOKEN_URL, { /* ... */ });
  const data = await res.json();
  cachedToken = data.access_token;
  expiresAt = Date.now() + data.expires_in * 1000;
  return cachedToken;
}

4. Kall API-et

Send det cachede tokenet som Bearer-header:

curl --request GET \
  --url https://connect.wennproperty.com/v1/projects \
  --header "Authorization: Bearer DIN_ACCESS_TOKEN"

Eller for å opprette en delingslenke:

curl --request POST \
  --url https://connect.wennproperty.com/v1/projects/abc-123/shares \
  --header "Authorization: Bearer DIN_ACCESS_TOKEN" \
  --header "content-type: application/json" \
  --data '{ "name": "Acme Tak AS" }'

Tenant-isolasjon

Tenant kommer fra tokenets tenant_id-krav og håndheves på serversiden. Du trenger ikke og må ikke sende noen X-Tenant-ID-header — den fjernes av API-et uansett. Dette betyr:

• Et token bundet til din tenant kan aldri lese en annen tenants data
• Det er ingen måte for en feil i din kode å lekke data på tvers av tenanter

client_id (fra sub-kravet) logges på hver forespørsel slik at aktiviteten kan revideres.

5. Håndter feil

Status	Betydning	Hva du skal gjøre
401	Tokenet er utløpt, ugyldig signatur, eller feil audience	Forny tokenet én gang og prøv igjen. Hvis det fortsatt feiler, er det en konfigurasjonsfeil — ikke loop
403	Tokenet er gyldig, men mangler påkrevd scope	Klienten har ikke scopen endepunktet krever. Sørg for at klienten ble opprettet med riktige scopes — opprett eller oppdater den om nødvendig. Aldri auto-recover ved å prøve igjen; det samme tokenet vil fortsette å feile
429	Rate-limit nådd	Respekter Retry-After-headeren. Implementér exponential backoff
5xx	Midlertidig serverfeil	Prøv igjen med exponential backoff og en taks for antall forsøk

Skill mellom forbigående (prøv igjen) og konfigurasjon (ikke prøv igjen) slik at du ikke hamrer token-endepunktet eller API-et på en permanent feil.

6. Rotering og tilbakekalling

Rotere client_secret

1. Åpne API-klienter-siden og roter klienten. En ny client_secret vises — kopier den umiddelbart.
2. Oppdater den nye secreten i din secret manager.
3. Tøm token-cachen din slik at neste forespørsel henter et nytt token med den nye secreten.
4. Bekreft at integrasjonen fungerer.

Token-endepunktet støtter to aktive secrets samtidig under rotering, så du kan rotere uten nedetid.

Tilbakekalling

Slett klienten fra API-klienter-siden for å tilbakekalle den. Etter tilbakekalling:

• Eksisterende access tokens forblir gyldige fram til exp (opptil 24 timer) — JWT-er kan ikke tilbakekalles, kun klienten kan
• Ingen nye tokens kan utstedes
• Når det cachede tokenet utløper, vil token-endepunktet returnere 403

Hvis du trenger umiddelbar tilbakekalling av alle aktive tokens (f.eks. ved hemmelighetslekkasje), kan Wenn Property-teamet rotere signeringsnøklene for å invalidere alt som er i flyt — ta kontakt. Dette påvirker alle integrasjoner på din tenant.