VDX Auth API — Quick reference (single-page)

Denne side er en komprimeret quick reference til eksterne udviklere der integrerer mod VDX Auth API via Keycloak OIDC.

For komplet dokumentation med detaljerede endpoint-beskrivelser, modeller, alle scenarier og flow-diagrammer, se den fulde guide.

---

Målgruppe

Tredjeparts-webapps der logger brugere ind via VDX Keycloak og vil hente brugerprofil, autorisationer og gruppekontekst fra VDX Auth API.

API'et beriger JWT-claims med VDX-data (organisationsnavn, gruppe-ID, management-autorisationer). Kald API'et efter login med brugerens access token.

Bemærk: OAuth2 Client Credentials er ikke understøttet. Backend-til-API med brugerens token er anbefalet.

---

Forudsætninger

1. Aftale med MedCom om Keycloak-klient og API-adgang — kontakt vdx@medcom.dk. Se adgangsvejledning.
2. Brugeren skal være kendt i VDX (lokal eller external via IdP).
3. JWT aud skal matche miljøet (stage default: organisation-audience).
4. CORS-whitelist hos MedCom hvis browseren kalder API'et direkte.

---

Authentication (essens)

1. Login via Authorization Code + PKCE mod Keycloak.
2. Modtag access_token + refresh_token.
3. Send i alle Auth API-kald:

Authorization: Bearer DIT_ACCESS_TOKEN

1. Valgfrit ved autorisationsskift: X-VDX-AuthorizationId: 42

Keycloak discovery (stage): https://login.vconf-stage.dk/auth/realms/broker/.well-known/openid-configuration

---

Base URLs og endpoints

Miljø	Base URL
Stage	https://mgmtauthapi.vconf-stage.dk
Produktion	https://mgmtauthapi.vconf.dk

Metode	Route	Formål
GET	/v1/user	Brugerprofil + organisationskontekst
GET	/v1/user/authorizations	Management-autorisationer
GET	/v1/user/group	Flad gruppe (effektiv kontekst)
GET	/v1/user/group/parents	Gruppe-træ fra rod

---

UserProfile (vigtigste model)

Returneres af GET /v1/user. Brug altid denne som sandhedskilde — ikke JWT-claims direkte.

Felt	Beskrivelse
organisationGroup	Effektiv gruppe-ID — brug i alle queries
organisationName	Visningsnavn for effektiv organisation
roles	Komma-separeret roller
isAuthorization	true ved autorisationsskift
authorizationId	Aktiv autorisations-ID (nullable)
hasAvailableAuthorizations	Vis autorisationsvælger i UI

Fuld model-reference

---

Integration (essens)

Mønster	Beskrivelse
A — Backend-til-API (anbefalet)	Backend kalder API med brugerens token. Tokens aldrig i browser.
B — Browser-til-API	SPA kalder API direkte. Kræver CORS-whitelist + sikker token-håndtering.

Login-flow: PKCE → token → GET /v1/user (obligatorisk) → afvis login ved 401/403 → persistér refresh token.

Detaljeret login-flow · Flow-diagrammer

---

Autorisationsskift (essens)

1. Hent liste: GET /v1/user/authorizations
2. Bruger vælger — send X-VDX-AuthorizationId: {id} på efterfølgende kald
3. Verificér med GET /v1/user — ved 403: afvis skift, log ikke ud
4. Slip: fjern header/persistens, kald GET /v1/user uden header

Detaljeret guide

---

Fejlkoder

HTTP	Betydning
401	Ugyldig/manglende JWT
403	Deaktiveret bruger eller ugyldig autorisation
404	Gruppe ikke fundet
429	Rate limit (100/min pr. IP)

Ved profil-kald efter login: fail closed — log brugeren ud ved 401/403/500.

Fejlkoder

---

Kodeeksempler — Python

import requests

AUTH_API = "https://mgmtauthapi.vconf-stage.dk"
TOKEN = "DIT_ACCESS_TOKEN"

# 1) Hent profil (obligatorisk efter login)
r = requests.get(f"{AUTH_API}/v1/user",
    headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
if r.status_code in (401, 403):
    raise RuntimeError("Login afvist")
profile = r.json()

# 2) Hent autorisationer
auths = requests.get(f"{AUTH_API}/v1/user/authorizations",
    headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30).json()

# 3) Skift autorisation
auth_id = auths[0]["id"]
r = requests.get(f"{AUTH_API}/v1/user",
    headers={"Authorization": f"Bearer {TOKEN}",
             "X-VDX-AuthorizationId": str(auth_id)}, timeout=30)
profile = r.json()  # isAuthorization == True

Alle Python-scenarier

---

Kodeeksempler — C

using System.Net.Http.Headers;
using System.Text.Json;

const string AuthApi = "https://mgmtauthapi.vconf-stage.dk";
const string Token = "DIT_ACCESS_TOKEN";

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };

// 1) Hent profil (obligatorisk efter login)
var req = new HttpRequestMessage(HttpMethod.Get, $"{AuthApi}/v1/user");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
var resp = await http.SendAsync(req);
if (resp.StatusCode is System.Net.HttpStatusCode.Unauthorized
    or System.Net.HttpStatusCode.Forbidden)
    throw new InvalidOperationException("Login afvist");

var profile = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());

// 3) Skift autorisation
var authReq = new HttpRequestMessage(HttpMethod.Get, $"{AuthApi}/v1/user");
authReq.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
authReq.Headers.TryAddWithoutValidation("X-VDX-AuthorizationId", "42");
var authResp = await http.SendAsync(authReq);

Alle C#-scenarier

---

Support

• E-mail: vdx@medcom.dk
• Fejlrapportering: medsend tidspunkt (UTC), sessionId, HTTP-status, fejl-payload, azp

Support-side · Kom i gang