Integrationsguide¶

Denne guide beskriver, hvordan du forbinder din backend-service til VDX Management API via OAuth2 Client Credentials.

Kom i gang¶

Forudsætninger¶

En registreret OAuth2-klient i VDX Keycloak med client_credentials grant type
Tildelt organisation_id som claim på klienten
Netværksadgang til Keycloak og API'ets base URL

Miljøer¶

Miljø	Base URL	Keycloak realm
Stage	`https://organisationapi.vconf-stage.dk`	`broker`

Produktionsmiljø

Produktions-URL'er udleveres ved onboarding. Kontakt vdx@medcom.dk for adgang.

Autentificering¶

API'et bruger OAuth2 Client Credentials flow. Din service henter et access token fra Keycloak og sender det som Bearer token på alle API-kald.

Token-endpoint discovery¶

Keycloak OpenID Connect discovery:

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

Token-endpoint udledes fra discovery-dokumentets token_endpoint felt.

Client Credentials flow¶

sequenceDiagram
    participant Service as Din service
    participant KC as Keycloak
    participant API as Management API

    Service->>KC: POST /token (client_id, client_secret, grant_type=client_credentials)
    KC-->>Service: access_token (JWT)
    Service->>API: GET /v1/organisation (Authorization: Bearer <token>)
    API-->>Service: 200 OK + JSON response

JWT-krav¶

Udstedte tokens skal indeholde følgende claims:

Claim	Beskrivelse
`azp` / `client_id`	Klientens identifikator
`dk:medcom:organisation_id`	Den organisation klienten er autoriseret til
`aud`	Skal indeholde `urn:medcom:organisationapi`

Audience-validering

Tokens uden urn:medcom:organisationapi i aud-claim afvises med 401 Unauthorized.

Token-eksempel (afkodet payload)¶

{
  "iss": "https://login.vconf-stage.dk/auth/realms/broker",
  "azp": "din-klient-id",
  "aud": "urn:medcom:organisationapi",
  "dk:medcom:organisation_id": "abc123-org-uuid",
  "exp": 1700000000,
  "iat": 1699999700
}

Scope-model¶

API'et håndhæver hierarkisk adgangskontrol baseret på klientens organisation_id.

Sådan virker det¶

organisation_id fra JWT opslås og resolves til en rod-gruppe (group_id)
Alle operationer skal rettes mod denne rod-gruppe eller en descendant (undergruppe)
Forsøg på at tilgå grupper eller brugere uden for hierarkiet returnerer 403 Forbidden

graph TD
    Root[Rod-gruppe organisation_id]
    A[Gruppe A]
    B[Gruppe B]
    C[Gruppe C undergruppe af A]
    External[Anden organisation]

    Root --> A
    Root --> B
    A --> C

    style External fill:#f99,stroke:#c00
    style Root fill:#9f9,stroke:#090

Eksempel

Hvis din klient er tilknyttet organisation X med rod-gruppe grp-001, kan du administrere grp-001 og alle grupper under den. Forsøg på at tilgå en gruppe under organisation Y returnerer 403 Forbidden.

Request-headers¶

Alle requests (undtagen health-endpoints) skal inkludere:

Header	Værdi
`Authorization`	`Bearer <access_token>`
`Content-Type`	`application/json` (ved POST/PUT)
`Accept`	`application/json`

Best practices¶

Token-caching¶

Cache access tokens i hukommelsen indtil kort før udløb (exp claim minus margin)
Undgå at hente nyt token pr. request — det belaster Keycloak unødigt og tæller mod rate limits

Idempotente operationer¶

PUT-operationer er idempotente og kan gentages sikkert ved timeout
POST-operationer (oprettelse) er ikke idempotente — brug passende retry-logik

Fejlhåndtering¶

Reagér på 429 Too Many Requests med exponential backoff
Ved 401 Unauthorized: hent nyt token og forsøg igen (maks. én gang)
Ved 403 Forbidden: request er uden for scope — gentag ikke

Paginering¶

Brug offset og limit query-parametre til lister
Standardværdi for limit er 50; maksimum er 200
Iterér med stigende offset indtil respons returnerer færre end limit elementer

Næste trin¶

Endpoints — fuld oversigt over alle operationer
Modeller — request/response-strukturer
Kodeeksempler — implementeringseksempler i curl, Python og C#