[Contratto pubblico curato]

API di Integrazione Esterna

Questa pagina documenta solo il contratto stabile di integrazione esterna. È volutamente limitata agli endpoint e alle garanzie di trasporto necessari agli integratori approvati.

Docs machine-readable Richiedi accesso avanzato

Confine di sicurezza

This documentation covers the stable external integration contract only. Platform internals, administrative routes, schema-level discovery, and partner-only capabilities are intentionally withheld from the public surface.

Nomi delle rotte, esempi di token e dettagli di trasporto restano in inglese canonico per allinearsi esattamente al contratto pubblico.

Verifica JWTOAuth e service tokenWebhookSolo trasporto GraphQLNessun dump di schemaNessuna rotta interna

URL base

Servizio auth: https://auth.knogin.com
Trasporto GraphQL: https://api.knogin.com/graphql
Docs machine-readable: https://knogin.com/api/docs

Contratto pubblico

Identità e registrazione app

Registra un’integrazione, consulta gli scope approvati e gestisci la governance di un’app esterna.

GET

/v1/platform/scopes

List available scopes

Returns the scope catalog that external apps can request during registration and token issuance.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Use this endpoint to build consent or admin approval workflows around approved scopes.
Do not assume unpublished scopes exist or are available to your tenant.

Esempio di request e response

Request

curl https://auth.knogin.com/v1/platform/scopes \
  -H "Authorization: Bearer <admin-access-token>"

Response

{
  "scopes": [
    {
      "name": "webhooks:write",
      "description": "Create and update outbound webhook subscriptions"
    }
  ]
}

GET/POST

/v1/platform/apps

Create and list platform apps

Creates an external integration app record or enumerates the apps already registered for the tenant.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Register a named app before attempting OAuth authorization code or client credentials flows.
The response includes client metadata, approved grants, and tenancy context.

Esempio di request e response

Request

curl -X POST https://auth.knogin.com/v1/platform/apps \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Case sync connector",
    "grant_types": ["client_credentials"],
    "redirect_uris": [],
    "requested_scopes": ["webhooks:write"]
  }'

Response

{
  "client_id": "app_123",
  "client_secret": "<write-once-secret>",
  "grant_types": ["client_credentials"],
  "requested_scopes": ["webhooks:write"]
}

GET

/v1/platform/apps/{client_id}

Inspect an integration app

Fetches the current metadata and governance state for a registered app by client identifier.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Use this endpoint to audit redirect URIs, grants, and scope posture before rotating secrets or enabling new workflows.

Esempio di request e response

Request

curl https://auth.knogin.com/v1/platform/apps/app_123 \
  -H "Authorization: Bearer <admin-access-token>"

Response

{
  "client_id": "app_123",
  "name": "Case sync connector",
  "grant_types": ["client_credentials"],
  "governance": {
    "allow_service_tokens": true
  }
}

PATCH

/v1/platform/apps/{client_id}/governance

Update app governance

Adjusts governance flags for an existing app without exposing tenant-wide administrative controls.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Admin cliente
Stabilità: Stabile

Use governance updates to constrain redirects, service token usage, and other tenant-approved behaviors.
This surface is scoped to the app identified in the path.

Esempio di request e response

Request

curl -X PATCH https://auth.knogin.com/v1/platform/apps/app_123/governance \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_service_tokens": true,
    "enforce_pkce": true
  }'

Response

{
  "client_id": "app_123",
  "governance": {
    "allow_service_tokens": true,
    "enforce_pkce": true
  }
}

Contratto pubblico

OAuth e service token

Usa flussi di token approvati per integrazioni user-delegated o machine-to-machine.

GET

/v1/oauth/authorize

Start OAuth authorization code flow

Initiates the authorization flow for integrations that act on behalf of a signed-in user.

Host: https://auth.knogin.com
Auth: OAuth authorization code
Audience: Integratori esterni
Stabilità: Stabile

Authorization requests should use the redirect URIs and scopes already approved on the platform app.
PKCE should be used whenever a confidential client secret is not available.

Esempio di request e response

Request

https://auth.knogin.com/v1/oauth/authorize?response_type=code&client_id=app_123&redirect_uri=https%3A%2F%2Fintegrator.example%2Fcallback&scope=webhooks%3Awrite&state=<opaque-state>&code_challenge=<pkce-challenge>&code_challenge_method=S256

Response

302 redirect to the registered redirect URI with either ?code=<authorization-code> or an OAuth error.

POST

/v1/oauth/token

Exchange or mint access tokens

Issues access tokens via authorization code or client credentials without documenting internal password or session flows.

Host: https://auth.knogin.com
Auth: OAuth auth code or client credentials
Audience: Integratori esterni
Stabilità: Stabile

Use authorization code for user-delegated access and client credentials for headless service integrations.
Only request scopes that were approved during app registration.

Esempio di request e response

Request

curl -X POST https://auth.knogin.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=app_123&client_secret=<client-secret>&scope=webhooks:write"

Response

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "webhooks:write"
}

POST

/v1/platform/apps/{client_id}/service-token

Mint a service token

Issues a service token for automation that should not depend on an end-user session.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Admin cliente
Stabilità: Stabile

Service tokens are appropriate for webhook management, scheduled exports, and other machine-to-machine workflows.
Keep service-token issuance behind tenant admin approval.

Esempio di request e response

Request

curl -X POST https://auth.knogin.com/v1/platform/apps/app_123/service-token \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["webhooks:write"]
  }'

Response

{
  "token": "<service-token>",
  "expires_at": "2026-03-24T10:00:00Z"
}

POST

/v1/platform/apps/{client_id}/rotate-secret

Rotate an app secret

Rotates a confidential client secret so an external integration can recover or rotate credentials safely.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Admin cliente
Stabilità: Stabile

Treat the rotated secret as write-once material and replace it in your secret store immediately.
Rotate secrets before revoking old credentials from automation.

Esempio di request e response

Request

curl -X POST https://auth.knogin.com/v1/platform/apps/app_123/rotate-secret \
  -H "Authorization: Bearer <admin-access-token>"

Response

{
  "client_id": "app_123",
  "client_secret": "<new-write-once-secret>"
}

Contratto pubblico

JWKS e verifica token

Verifica i JWT emessi da Knogin contro chiavi pubbliche.

GET

/.well-known/jwks.json

OpenID-compatible JWKS discovery

Publishes public signing keys at the well-known JWKS path for standards-based token validation.

Host: https://auth.knogin.com
Auth: Public
Audience: Integratori esterni
Stabilità: Stabile

Use the key identifier in the JWT header to select the correct public key.
Cache JWKS responses according to your verifier policy and refresh on unknown key IDs.

Esempio di request e response

Request

curl https://auth.knogin.com/.well-known/jwks.json

Response

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "2026-03-signing-key",
      "use": "sig"
    }
  ]
}

GET

/v1/auth/jwks.json

Versioned JWKS endpoint

Provides the same public signing material under the auth-service versioned API namespace.

Host: https://auth.knogin.com
Auth: Public
Audience: Integratori esterni
Stabilità: Stabile

Use this variant when your API client standardizes on versioned endpoints.

Esempio di request e response

Request

curl https://auth.knogin.com/v1/auth/jwks.json

Response

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "2026-03-signing-key",
      "use": "sig"
    }
  ]
}

Contratto pubblico

Consegna eventi e webhook

Crea, testa e osserva consegne webhook in uscita per integrazioni approvate.

GET/POST

/v1/webhooks

Create and list webhooks

Manages outbound webhook subscriptions used to deliver approved event notifications to an external system.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Create subscriptions only for events your integration has been approved to receive.
Outbound webhook secrets should be stored and rotated like any other integration credential.

Esempio di request e response

Request

curl -X POST https://auth.knogin.com/v1/webhooks \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://integrator.example/webhooks/argus",
    "events": ["incident.updated"],
    "secret": "<signing-secret>"
  }'

Response

{
  "id": "wh_123",
  "url": "https://integrator.example/webhooks/argus",
  "events": ["incident.updated"]
}

GET/PUT/DELETE

/v1/webhooks/{webhook_id}

Inspect, update, or delete a webhook

Manages an individual webhook subscription by identifier.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Use update operations to rotate secrets or adjust event selections without recreating the subscription.

Esempio di request e response

Request

curl -X PUT https://auth.knogin.com/v1/webhooks/wh_123 \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["incident.updated", "incident.closed"]
  }'

Response

{
  "id": "wh_123",
  "events": ["incident.updated", "incident.closed"]
}

GET

/v1/webhooks/{webhook_id}/deliveries

Review delivery attempts

Returns historical delivery attempts for a webhook so integrators can debug retries and downstream failures.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Use delivery history instead of internal logs to diagnose receiver behavior.
Delivery metadata is limited to the webhook in scope.

Esempio di request e response

Request

curl https://auth.knogin.com/v1/webhooks/wh_123/deliveries \
  -H "Authorization: Bearer <access-token>"

Response

{
  "deliveries": [
    {
      "id": "dlv_123",
      "status": "succeeded",
      "attempted_at": "2026-03-23T12:00:00Z"
    }
  ]
}

POST

/v1/webhooks/{webhook_id}/test

Send a test webhook

Triggers a synthetic delivery to validate receiver configuration before enabling production traffic.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Use test deliveries when rotating secrets or validating a new endpoint.

Esempio di request e response

Request

curl -X POST https://auth.knogin.com/v1/webhooks/wh_123/test \
  -H "Authorization: Bearer <access-token>"

Response

{
  "delivery_id": "dlv_test_123",
  "status": "queued"
}

Contratto pubblico

Contratto di trasporto GraphQL

Connettiti al trasporto GraphQL condiviso senza pubblicare schema o inventario operazioni.

POST

/graphql

Use the shared GraphQL transport

Connect to the GraphQL endpoint with bearer tokens and tenant scoping, while operation bundles remain curated and access-controlled.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Public documentation covers transport, headers, tenancy, and error handling only.
Schema dumps, playground access, introspection guidance, and unpublished operations are excluded from the public contract.
Approved partners receive curated operation bundles tied to explicit integration workflows.

Esempio di request e response

Request

curl -X POST https://api.knogin.com/graphql \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: <tenant-id>" \
  -d '{
    "query": "<approved GraphQL document>",
    "variables": {}
  }'

Response

{
  "data": {
    "result": "Returned for your approved operation bundle"
  }
}

GET

/api/v1/epcr/encounters/{encounterId}

Fetch an ePCR encounter

Retrieve the partner-facing summary of an electronic patient care record encounter, or a FHIR R4 Bundle when ?format=fhir.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Partners receive a de-identified projection; full PII (DOB, NOK contact, street address) remain internal.
Pass ?format=fhir for an interoperability-ready FHIR R4 transaction Bundle.

Esempio di request e response

Request

curl https://api.knogin.com/api/v1/epcr/encounters/enc_123 \
  -H "Authorization: Bearer <access-token>"

Response

{
  "id": "enc_123",
  "organization_id": "org_1",
  "care_model": "prehospital_emergency",
  "status": "in_progress"
}

GET

/api/v1/epcr/encounters/{encounterId}/fhir-bundle

Export encounter as FHIR R4 Bundle

Return a FHIR R4 transaction Bundle for an ePCR encounter, suitable for handover into hospital EHRs.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Bundle contains Patient, Encounter, Observation, Procedure, MedicationAdministration, and Composition resources.

Esempio di request e response

Request

curl https://api.knogin.com/api/v1/epcr/encounters/enc_123/fhir-bundle \
  -H "Authorization: Bearer <access-token>"

Response

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": []
}

POST

/api/v1/epcr/encounters

Create an ePCR encounter

Create a new ePCR encounter from an external CAD-to-ePCR integration, scoped to the caller's organisation.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Requires the argus:epcr:write scope on the calling service token.

Esempio di request e response

Request

curl -X POST https://api.knogin.com/api/v1/epcr/encounters \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "care_model": "prehospital_emergency",
    "vehicle_id": "AMB-42",
    "crew_ids": ["usr_1"],
    "cad_incident_id": "cad_999"
  }'

Response

{
  "id": "enc_123",
  "status": "in_progress"
}

GET

/api/v1/devices

List medical devices

List IEEE 11073 PHD-enrolled medical devices for the caller's organisation, optionally filtered by vehicle.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Supported device classes: defib, ecg, oximeter, bp, glucose, etco2, thermometer, multiparameter.

Esempio di request e response

Request

curl "https://api.knogin.com/api/v1/devices?vehicle_id=AMB-42" \
  -H "Authorization: Bearer <access-token>"

Response

[
  {
    "id": "dev_1",
    "serial_number": "SN-0001",
    "device_class": "defib",
    "status": "active"
  }
]

POST

/api/v1/devices/enrol

Enrol a medical device

Enrol (or re-enrol) a medical device for this organisation so it can emit IEEE 11073 PHD observations.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Requires the argus:devices:write scope on the calling service token.

Esempio di request e response

Request

curl -X POST https://api.knogin.com/api/v1/devices/enrol \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN-0001",
    "device_class": "defib",
    "manufacturer": "ACME"
  }'

Response

{
  "id": "dev_1",
  "serial_number": "SN-0001",
  "device_class": "defib",
  "status": "active"
}

POST

/api/v1/devices/{deviceId}/observations

Submit a PHD observation

Submit a single IEEE 11073 PHD observation (MDC metric code + UCUM unit) from an enrolled device.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Use mdc_code from ISO/IEEE 11073-10101 and unit_code from UCUM.
Optionally link the observation to an ePCR encounter via encounter_id.

Esempio di request e response

Request

curl -X POST https://api.knogin.com/api/v1/devices/dev_1/observations \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mdc_code": "MDC_PULS_OXIM_SAT_O2",
    "value": 98.0,
    "unit_code": "%"
  }'

Response

{
  "id": "obs_1",
  "device_id": "dev_1",
  "mdc_code": "MDC_PULS_OXIM_SAT_O2",
  "value": 98.0,
  "unit_code": "%"
}

query acqiMetrics(fromDate, toDate)

Query ACQI metrics

Retrieve Ambulance Clinical Quality Indicator metrics with sparkline trend data over a date range (GraphQL).

Host: https://api.knogin.com
Auth: Bearer token
Audience: Integratori esterni
Stabilità: Stabile

Requires the argus:acqi:read scope on the calling service token.

Esempio di request e response

Request

curl -X POST https://api.knogin.com/graphql \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($from: DateTime!, $to: DateTime!) { acqiMetrics(fromDate: $from, toDate: $to) { name value numerator denominator unit } }",
    "variables": { "from": "2026-04-01T00:00:00Z", "to": "2026-04-17T00:00:00Z" }
  }'

Response

{
  "data": {
    "acqiMetrics": [
      {
        "name": "rosc_survival",
        "value": 0.32
      }
    ]
  }
}

Disponibile su richiesta

Telephony provider configuration

Manage pluggable telephony providers and DID routing rules. Supported carriers: VoIP.ms, Twilio, Telnyx, Plivo, Bandwidth, generic SIP/IAX2 via gateway. Requires the argus:telephony:write scope.

query telephonyProviders(tenantId)

List telephony providers

Returns all configured telephony providers for a tenant, including carrier type, default flag, and active status. Credentials are never returned.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Partner strategici
Stabilità: Stabile

Requires the argus:telephony:read scope.
credentials_enc is never returned — the field is excluded from the external contract.
Added in contract v2026.2.

La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.

Richiedi accesso

query telephonyRoutes(tenantId, providerId)

List telephony routes (DID routing)

Returns all DID routing rules for a tenant, mapping phone numbers or provider subaccounts to a target subsystem (psap, municipal, utilities, etc.).

Host: https://api.knogin.com
Auth: Bearer token
Audience: Partner strategici
Stabilità: Stabile

Requires the argus:telephony:read scope.
Added in contract v2026.2.

La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.

Richiedi accesso

Disponibile su richiesta

Capacità avanzate su richiesta

API di piattaforma ampliate, bundle GraphQL curati e federazione restano dietro accesso revisionato.

/api/v1/platform/*

Platform control-plane APIs

Expanded control-plane workflows under /api/v1/platform are available only through approved partner or customer programs.

Host: https://api.knogin.com
Auth: Request access
Audience: Partner strategici
Stabilità: Approvato su richiesta

Public docs intentionally stop at a high-level capability description.
Examples include deployment packages, automations, agents, marketplace flows, and release operations.

La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.

Richiedi accesso

Curated GraphQL operations by approved workflow

Curated GraphQL operation bundles

Approved integrations can receive a narrow set of GraphQL operations derived from vetted FE2 workflows instead of full schema discovery.

Host: https://api.knogin.com
Auth: Request access
Audience: Partner strategici
Stabilità: Approvato su richiesta

Examples include incident webhook configuration flows and other explicitly approved bundles.
This is the mechanism for exposing integrations without publishing the full GraphQL schema.

La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.

Richiedi accesso

/v1/saml/*

Enterprise federation and SAML

Federation setup and SAML onboarding are handled through guided implementation rather than a self-serve public blueprint.

Host: https://auth.knogin.com
Auth: Request access
Audience: Admin cliente
Stabilità: Approvato su richiesta

Enterprise identity integrations require tenant-specific coordination and are not documented as an open public API.

La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.

Richiedi accesso

Hai bisogno di accesso a integrazioni avanzate?

Usa la richiesta di integrazione per bundle GraphQL curati, accesso alla piattaforma, federazione enterprise o sandbox onboarding.