Integrationsguide¶

Foretrækker du alt på én side? Se single-page versionen.

Kom i gang¶

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

Forudsætninger¶

Aftale med MedCom om Keycloak-klient og adgang til MedCom Video API. Se adgangsvejledning og kontakt vdx@medcom.dk.
Brugeren skal være kendt i VDX med gyldig organisation.
JWT access token skal indeholde organisation, email og mindst én meeting-rolle (se Autentificering).
CORS og host: Din webapps origin skal whitelistes hos MedCom, hvis browseren kalder API'et direkte.

Miljøer¶

Miljø	Video API base URL	Keycloak discovery (stage)
Stage	`https://videoapi.vconf-stage.dk`	`https://login.vconf-stage.dk/auth/realms/broker/.well-known/openid-configuration`
Produktion	`https://videoapi.vconf.dk`	`https://login.vconf.dk/auth/realms/broker/.well-known/openid-configuration`

Bekræft den konkrete produktions-URL og Keycloak-konfiguration hos MedCom.

API-version¶

Brug v2 (/v2/...). v1 er under udfasning og anvender ældre timestamp-format samt SAML-attributter i stedet for OAuth2/JWT-claims. Se v1/v2-forskelle.

Autentificering¶

Flow¶

Log brugeren ind i din app via Authorization Code Flow (anbefalet med PKCE) mod VDX Keycloak.
Modtag et access token fra Keycloak efter succesfuldt login.
Send access token i alle kald til MedCom Video API:

Authorization: Bearer DIT_ACCESS_TOKEN

Forny token via dit OIDC-biblioteks refresh-logik, når access token udløber.

Påkrævede JWT-claims¶

v2 anvender OAuth2. Token skal indeholde claims svarende til følgende (claim-navne er konfigurerbare, men værdierne er faste):

Claim	Beskrivelse
Organisation	Hvilken organisation brugeren tilhører
Email	Brugerens email
User role	Mindst én meeting-rolle (se nedenfor)

Standard claim-navne i VDX-miljøer (bekræft ved adgangsanmodning):

userservice.token.attribute.organisation
userservice.token.attribute.email
userservice.token.attribute.userrole

Se også JWT-claims og roller.

Roller og adgang¶

API'et understøtter flere roller pr. bruger. Adgang styres pr. endpoint. Kun følgende roller er relevante for eksterne integrationer:

Rolle	Beskrivelse	Typiske endpoints
`meeting-user`	Normal mødebruger — egne møder	GET/PUT/PATCH/DELETE egne møder, søgning
`meeting-planner`	Planlægger — møder i egen organisation, evt. på vegne af andre via `organizedByEmail`	Opret/opdater møder i organisation
`meeting-admin`	Administrator — templates, pool-reservation og fuld adgang	POST/PUT/DELETE scheduling-templates, scheduling-info-reserve

Adgangsmatrix (v2 — overordnet)¶

Operation	meeting-user	meeting-planner	meeting-admin
Opret møde (POST /v2/meetings)	Ja	Ja	Ja
Opdater/slet møde	Ja (egne)	Ja (org)	Ja
Læs scheduling info	Ja	Ja	Ja
Læs scheduling templates	Ja	Ja	Ja
Scheduling templates (opret/opdater/slet)	Nej	Nej	Ja
Pool-reservation	Nej	Nej	Ja

Organisationsgrænser gælder: brugere ser typisk kun data inden for egen organisations træ.

Integrationsmønstre¶

A) Backend-til-API (anbefalet)¶

Din apps backend kalder Video API på vegne af brugeren:

Brugeren logger ind via Keycloak mod din webapp.
Access og refresh tokens gemmes server-side.
Backend kalder API'et med Authorization: Bearer <brugerens access_token>.
Brugeren ser aldrig access token i browseren.

Fordele: Ingen tokens i browser, ingen CORS-konfiguration, centraliseret fejlhåndtering.

B) Browser-til-API (direkte fra frontend)¶

SPA-style frontends kan kalde API'et direkte, hvis:

Din webapps origin er whitelisted hos MedCom.
Frontend håndterer Keycloak login og opbevarer tokens sikkert.
Hvert fetch-kald sætter Authorization-header manuelt.

Ulemper: Tokens i browser, CORS skal aftales pr. miljø.

Opret møde-flow¶

Typisk flow for booking-integration:

sequenceDiagram
    participant App as Din app
    participant Keycloak
    participant VideoAPI as Video API v2

    App->>Keycloak: Login (Authorization Code)
    Keycloak->>App: access_token
    App->>VideoAPI: GET /v2/scheduling-templates
    VideoAPI->>App: Templates for organisation
    App->>VideoAPI: POST /v2/meetings
    VideoAPI->>App: Meeting (uuid, shortLink, _links)
    App->>VideoAPI: GET /v2/scheduling-info/{uuid}
    VideoAPI->>App: Scheduling info (uriWithDomain, pins)

Trin-for-trin¶

Autentificér brugeren og hent access token.
Valgfrit: Hent scheduling templates med GET /v2/scheduling-templates for at vælge schedulingTemplateId.
Opret møde med POST /v2/meetings — minimum subject, startTime, endTime.
Gem uuid fra responsen — bruges til opdatering og scheduling info.
Hent scheduling info via _links.scheduling-info eller GET /v2/scheduling-info/{uuid} for mødelink, URI og PIN-koder.
Vis shortLink/portalLink til brugeren.

Template-valg ved oprettelse¶

Ved POST /v2/meetings vælges template i denne rækkefølge:

schedulingTemplateId i request (hvis gyldig)
Organisationens default template
Fælles default template (uden organisation)

Opdateringsregler for møder¶

provisionStatus	PUT/PATCH tilladt	Bemærkning
`AWAITS_PROVISION`	Fuld opdatering	Standard før provisionering
`PROVISIONED_OK`	Kun `endTime` (PUT/PATCH)	Efter succesfuld provisionering
Andet	Typisk 406	Se endpoint-dokumentation

Sletning (DELETE /v2/meetings/{uuid}) er kun tilladt når provisionStatus er AWAITS_PROVISION.

Pool-reservation¶

Organisationer med pool-møder kan reservere scheduling info før mødet oprettes:

GET /v2/scheduling-info-reserve — reservér fra pool (kræver meeting-admin).
Gem reservationId fra responsen.
Ved POST /v2/meetings: angiv schedulingInfoReservationId — ikke kombiner med guestPin/hostPin.

Best practices¶

Brug v2-endpoints og ISO 8601 timestamps med offset (Z eller +02:00).
Gem altid uuid fra møde-responsen — det er primær nøgle.
Brug externalId til idempotens/kobling til dit eget system.
Håndter 406 Not Acceptable ved forsøg på opdatering/sletning i forkert provisionStatus.
Ved fejl: læs detailedError.errorCode og errorText i respons-body.

Se også Fejlkoder, Endpoints og Kodeeksempler.

Ændringshistorik¶

Dato	Ændring
2026-06-27	Første integrationsguide for MedCom Video API v2