API-toegang regelen

Ons API gebruikt clientcertificaten voor API-toegang. Zie certificaatvereisten voor de technische vereisten. Ons API biedt certificaten aan met toegang op drie verschillende niveaus, dit zijn de volgende:

Voor globale en connectorcertificaten is STAGE precies DEVELOPMENT, STAGING of PRODUCTION (hoofdletters). Gebruik de supplier code uit het dashboard en de technische naam van de bestaande connector zoals die daar staat, niet de weergavenaam. Gebruik voor een omgevingscertificaat de klantcode van die omgeving. TE1002 is de Nedap development-omgeving. De stage van het certificaat moet bij de doelomgeving passen.

Een bredere scope geeft niet zelfstandig toegang. De zorgorganisatie moet de connectorversie voor de betreffende omgeving goedkeuren. Eén globaal of connectorcertificaat kan meerdere goedgekeurde omgevingen bedienen, elk met eigen toestemming.

De CN bestaat uit precies drie delen, gescheiden door -. De identificatie mag alleen a-z, A-Z, 0-9 en _ bevatten; klantcodes zijn in hoofdletters. Kies de smalste scope die past: gebruik een globaal certificaat alleen als één systeem meerdere connectoren bedient.

Omgeving toevoegen en toegang aanvragen

Hieronder volgt een stappenplan om toegang tot een klantomgeving aan te vragen voor een versie van je koppeling. Heb je nog geen versie van je koppeling ingericht? Zie dan een koppeling specificeren

Ontwikkel je als zorgorganisatie voor je eigen Ons-omgevingen? Je omgevingen zullen al in het overzicht Customers van de connector staan. De bedoeling is dat je daar een omgeving opent en via Request version (of Change version als er al een versie actief is) de gewenste versie als pending version aanvraagt, net als bij een versie-upgrade. De knop New environment is voor zorgorganisaties niet beschikbaar.

1. Open Connectors, selecteer de connector en open Customers.
2. Kies New environment. Zoek op naam van de zorgorganisatie of volledige klantcode en selecteer de omgeving en connectorversie.
3. Kies Add environment. De geselecteerde versie wordt pending. De zorgorganisatie kan het verzoek goedkeuren of afwijzen in Ons Podium. Conceptversies kunnen alleen op development-omgevingen worden gebruikt; zet een versie vast voordat je staging- of productietoegang aanvraagt.
4. Open de klantomgeving om de huidige en aangevraagde versie, toestemmingsstatus en certificaatdekking te zien. Toegang ontstaat pas na goedkeuring van de versie en met een actief certificaat dat de omgeving dekt.

Nieuwe versie aanvragen voor een bestaande omgeving

Open de omgeving onder Customers en kies Change version. Selecteer de nieuwe versie en kies Request change. De huidige goedgekeurde versie blijft in gebruik zolang de nieuwe versie pending is. De zorgorganisatie kan het verzoek in Ons Podium goedkeuren of afwijzen. Na goedkeuring gebruikt de omgeving de nieuwe versie. Een certificaat met passende scope en stage blijft bruikbaar, mits de nieuwe versie is goedgekeurd.

Certificaten regelen en gebruiken

Genereer een CSR met een RSA-sleutel van ten minste 4096 bits. Alleen de common name (CN) is verplicht; velden zoals OU, O, L, ST, C en e-mailadres hoef je niet in te vullen. Met -subj vul je in de onderstaande OpenSSL-voorbeelden alleen de CN in. Vervang de voorbeeldwaarden door je eigen supplier code, technische connectornaam, klantcode, stage en identificatie. De commando’s maken elk een CSR- en een KEY-bestand. Bewaar het KEY-bestand veilig en deel het nooit, ook niet met Nedap. Upload alleen de CSR. Is de privésleutel toch gedeeld? Trek het certificaat dan direct in - en/of schakel het uit - via het Ons API Dashboard (Revoke serial), genereer een nieuwe sleutel en CSR, en informeer Nedap.

Globaal certificaat

Voorbeeld-CN: ONSAPI_000-DEVELOPMENT-example.

openssl req -out ONSAPI_000-DEVELOPMENT-example.csr -new -newkey rsa:4096 -nodes -keyout ONSAPI_000-DEVELOPMENT-example.key -subj "/CN=ONSAPI_000-DEVELOPMENT-example"

Open het Connectors-overzicht en toon zo nodig de certificaatkaarten onder Global. Klik op de certificaatstatuskaart en kies in het venster Upload a CSR file. Bevestig met Upload CSR. De CSR wordt direct ondertekend.

Stuur bij elk API-verzoek met dit certificaat de HTTP-headers X-Connector-Technical-Name met de technische naam van de doelconnector (bijvoorbeeld example_connector) en X-Customer-Code met de klantcode van de doelomgeving (bijvoorbeeld TE1002) mee.

Connectorcertificaat

Voorbeeld-CN: example_connector-DEVELOPMENT-example.

openssl req -out example_connector-DEVELOPMENT-example.csr -new -newkey rsa:4096 -nodes -keyout example_connector-DEVELOPMENT-example.key -subj "/CN=example_connector-DEVELOPMENT-example"

Open de connector en ga naar de certificaatkaarten. Klik op de certificaatstatuskaart onder Connector en kies Upload a CSR file. Bevestig met Upload CSR. De CSR wordt direct ondertekend.

Stuur bij elk API-verzoek met dit certificaat de HTTP-header X-Customer-Code met de klantcode van de doelomgeving mee, bijvoorbeeld TE1002. De connector staat al in de CN. Stuur je ook X-Connector-Technical-Name mee, dan moet die overeenkomen met de connector in de CN.

Omgevingscertificaat

Voorbeeld-CN: example_connector-TE1002-example.

openssl req -out example_connector-TE1002-example.csr -new -newkey rsa:4096 -nodes -keyout example_connector-TE1002-example.key -subj "/CN=example_connector-TE1002-example"

Open bij de connector Customers en selecteer de klantomgeving. Gebruik in de sectie Certificates de certificaatstatuskaart of Renew bij een bestaand certificaat. Kies Upload a CSR file en bevestig met Upload CSR. De CSR kan wachten op goedkeuring van de klanttoestemming voordat het certificaat wordt ondertekend.

Voor API-verzoeken met dit certificaat zijn deze HTTP-headers niet nodig: de connector en klantcode staan al in de CN. Stuur je X-Connector-Technical-Name of X-Customer-Code toch mee, dan moet de waarde overeenkomen met de CN.

Na ondertekening vind je het certificaat op dezelfde plek: open de connector, ga naar Customers en selecteer de omgeving. Klik in de sectie Certificates op het downloadpictogram rechts van de vervaldatum om het PEM-bestand te downloaden.