Integrationsguide¶

Kom i gang¶

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

Forudsætninger¶

Organisation i VDX med adgang til Pexip History Service.
API-nøgle oprettet af en bruger med rollen management-admin i VDX Management. Se API-nøgle.
Backend-integration anbefales — gem API-nøglen server-side, aldrig i browser/frontend.

Miljøer¶

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

Alle endpoints nedenfor er relative til base URL (fx GET https://historyapi.vconf-stage.dk/apikey/status/v1/conference/list).

Autentificering¶

API'et bruger API-nøgle i HTTP-header — ikke OAuth2/JWT.

X-API-KEY: DIN_API_NOEGLE

Send headeren i alle kald til apikey-endpoints.

API-nøgle¶

API-nøglen oprettes af organisationens administrator:

Log ind i VDX Management med en bruger der har rollen management-admin.
Gå til organisationens API-nøgle-indstillinger (typisk under organisation/administration).
Opret en ny API-nøgle til Pexip History Service.
Gem nøglen sikkert server-side — den vises typisk kun én gang ved oprettelse.

Adgang: API-nøglen giver adgang til data inden for organisationens hierarki — dvs. egen organisation og underorganisationer, afhængigt af nøglens scope.

Sikkerhed:

Gem API-nøglen i Secret Manager / miljøvariabler — aldrig i kildekode eller frontend.
Rotér nøglen ved mistanke om kompromittering.
Brug separate nøgler pr. miljø (stage/produktion).

Endpoint-grupper¶

API'et har to grupper af apikey-endpoints:

Gruppe	Prefix	Formål
Live-status	`/apikey/status/v1/conference/...`	Aktive/igangværende konferencer og deltagere
Historic	`/apikey/history/v1/conference/...`	Afsluttede konferencer i datointerval

Se Endpoints for komplet oversigt.

Integrationsmønstre¶

A) Backend polling (anbefalet)¶

Din apps backend kalder History API med API-nøgle:

Gem API-nøgle server-side (miljøvariabel/secret).
Poll live-status med passende interval (fx hvert 30.–60. sekund).
Hent historik on-demand eller via planlagt job (fx daglig rapport).

Fordele: API-nøgle eksponeres aldrig i browser, centraliseret fejlhåndtering.

B) Planlagt historik-hentning¶

For rapportering og statistik:

Kør batch-job (fx natligt) med GET /apikey/history/v1/conference.
Angiv start_time__gte og end_time__lt for ønsket periode.
Brug limit til at paginere store datamængder.

Live overvågning — flow¶

Typisk flow for dashboard/overvågning:

sequenceDiagram
    participant App as Din backend
    participant HistoryAPI as Pexip History Service

    loop Poll hvert 30-60 sek
        App->>HistoryAPI: GET /apikey/status/v1/conference/list
        HistoryAPI->>App: Array af live-conference
    end
    App->>HistoryAPI: GET /apikey/status/v1/conference/{uri}
    HistoryAPI->>App: live-conference med deltagere

Historisk rapportering — flow¶

sequenceDiagram
    participant App as Din backend
    participant HistoryAPI as Pexip History Service

    App->>HistoryAPI: GET /apikey/history/v1/conference?start_time__gte=...&end_time__lt=...
    HistoryAPI->>App: Array af historic-conference
    App->>HistoryAPI: GET /apikey/history/v1/conference/{conference_id}
    HistoryAPI->>App: Enkelt historic-conference med detaljer

Best practices¶

Brug ISO 8601 datetime i query-parametre (start_time__gte, end_time__lt).
Poll live-status med fornuftigt interval — undgå aggressiv polling (anbefalet: 30–60 sek.).
Brug limit ved historik-hentning for at undgå store payloads.
Håndter 404 som "ingen data" — ikke nødvendigvis fejl.
API-nøglen er read-only — ingen write-operationer eksponeres.

Se også Fejlkoder, Endpoints og Kodeeksempler.

Ændringshistorik¶

Dato	Ændring
2026-06-27	Rettet base URL til `historyapi.vconf.dk` / `historyapi.vconf-stage.dk`
2026-06-27	Første integrationsguide for VDX Pexip History Service