Integrationsguide¶

Kom i gang¶

Før integration skal følgende være på plads:

Forudsætninger¶

Aftale med MedCom om Keycloak-klient og adgang til Device Registration Service. Se adgangsvejledning og kontakt vdx@medcom.dk.
Organisation — enheder oprettes inden for egen organisation eller underorganisationer.
JWT access token med relevant meeting-rolle (se Autentificering).
Backend-integration anbefales for admin-operationer — gem tokens server-side.

Miljøer¶

Miljø	Base URL
Stage	`https://videoapi.vconf-stage.dk/devicereg`
Produktion	`https://videoapi.vconf.dk/devicereg`

Endpoints er under prefix /v1/... (fx POST https://videoapi.vconf-stage.dk/devicereg/v1/device).

Keycloak (stage): https://login.vconf-stage.dk/auth/realms/broker

Autentificering¶

OAuth2 (de fleste endpoints)¶

Log brugeren/enheden ind via Authorization Code Flow (anbefalet med PKCE) eller Client Credentials mod VDX Keycloak.
Modtag et access token fra Keycloak.
Send access token i alle beskyttede kald:

Authorization: Bearer DIT_ACCESS_TOKEN

Roller pr. endpoint-gruppe¶

Gruppe	Roller	Beskrivelse
Device Admin	`meeting-admin`	CRUD enheder, push møder/beskeder, creation tokens
Device Admin (list)	`meeting-admin`, `meeting-user`, `meeting-planner`	List enheder — for `meeting-user`/`meeting-planner` skal token identificere en eksisterende enhed
Device Comm	`meeting-user`, `meeting-planner`	Heartbeat, hent meeting/message — token skal identificere enheden
Device Login (one-click)	`meeting-admin`	Generer login-link
Device Login (login, device-login)	Ingen — public endpoints	Hent token via login-id eller creation token

Public endpoints¶

To endpoints kræver ikke Bearer token:

GET /v1/login/{id} — hent access token via one-click login-id
POST /v1/device-login — opret enhed og hent access token via device creation token

Device-lifecycle¶

sequenceDiagram
    participant Admin as Admin backend
    participant API as Device Registration
    participant KC as Keycloak
    participant Device as Videoudstyr

    Admin->>API: POST /v1/device
    API->>KC: Opret device-bruger
    API->>Admin: device + keycloak_password
    Admin->>Device: Konfigurer short_id + password
    Device->>KC: Login med device credentials
    Device->>API: GET /v1/heartbeat

Typiske trin¶

Opret enhed med POST /v1/device — modtag id, short_id og keycloak_password.
Konfigurer enheden med credentials (short_id som username, keycloak_password).
Enheden logger ind i Keycloak og modtager device-token.
Heartbeat med GET /v1/heartbeat for at verificere forbindelse.
Opdater/slet via PUT/DELETE /v1/device/{id} efter behov.
Nyt password med GET /v1/device/{id}/password hvis credentials skal roteres.

Auto-oprettelse via creation token¶

Alternativt flow uden manuel device-oprettelse:

Admin opretter token: POST /v1/device-creation-token
Enhed kalder public endpoint: POST /v1/device-login med token
Enhed modtager access token direkte

Meeting-kø-flow¶

Admin pusher møder til en enhed; enheden poller og henter det ældste ubehandlede møde.

sequenceDiagram
    participant Admin as Admin backend
    participant API as Device Registration
    participant Device as Videoudstyr

    Admin->>API: POST /v1/meetings
    Note over Admin,API: device_id, uri, pin, meeting_type
    loop Poll
        Device->>API: GET /v1/meeting
        API->>Device: MEETING_FOUND + meeting
    end
    Device->>Device: Deltag i møde
    Admin->>API: DELETE /v1/meetings/{device_id}
    Note over Admin,API: Ryd kø efter behov

Meeting-felter¶

Felt	Beskrivelse
`uri`	Møde-URI uden domæne (fx `574893`)
`pin`	Møde-PIN (1000–999999999)
`meeting_type`	Mødetype (fx `oneway-nosound`)
`meeting_host`	Vært (valgfri)
`meeting_description`	Beskrivelse (valgfri)

Message-kø-flow¶

Samme polling-mønster som meetings — admin pusher beskeder, enhed henter via GET /v1/message.

Admin: POST /v1/messages med device_id, key og value
Enhed: GET /v1/message — returnerer MESSAGE_FOUND + besked eller NO_WAITING_MESSAGES
Admin: DELETE /v1/messages/{device_id} — ryd kø

Til enheder der skal logges ind uden manuel credential-konfiguration:

Admin: GET /v1/one-click/{device_id}?client-id=... — modtag login-link
Enhed/browser åbner linket → redirect til GET /v1/login/{login_id}
Modtag accessToken med device JWT

Best practices¶

Gem keycloak_password sikkert ved oprettelse — den returneres kun én gang.
Brug polling med fornuftigt interval (fx 5–10 sek.) for meeting/message-kø.
Ryd køer med DELETE /v1/meetings/{id} / DELETE /v1/messages/{id} efter behandling.
Enheder kan kun tilgå data i egen organisation og underorganisationer.
deviceRole skal matche enhedens faktiske adgang: MEETING_USER eller MEETING_PLANNER.
Brug audiences til at give enheden adgang til yderligere API'er (enheden har altid adgang til Device Registration API).

Se også Endpoints, Modeller og Kodeeksempler.

Ændringshistorik¶

Dato	Ændring
2026-06-27	Første integrationsguide for VDX Device Registration Service