API Keys

API keys zijn de authenticatiemethode voor de Ultimo REST API. Elke API key definieert welke entiteiten, properties en workflows beschikbaar zijn, en is gekoppeld aan een systeemgebruiker voor autorisatie. API keys worden aangemaakt en beheerd in de Ultimo Configuration Tool (UCT).

Beschikbaarheid: Professional, Premium, Enterprise

Wat is een API Key?bewerken

Een API key is een uniek geheim (secret) dat wordt meegegeven in de header van elk REST API request. De key bepaalt: - Welke entiteiten toegankelijk zijn (Equipment, Job, Article, etc.) - Welke properties per entiteit zichtbaar zijn - Welke operaties zijn toegestaan (lezen, schrijven, verwijderen) - Welke workflows kunnen worden aangeroepen - Welke autorisatie geldt (via de gekoppelde systeemgebruiker)

API Key aanmaken in UCTbewerken

Stappenbewerken

1. Open de Ultimo Configuration Tool (UCT)
2. Navigeer naar Business Integration > REST API Keys
3. Klik op Nieuwe API Key
4. Configureer de basisinstellingen:
5. Naam: Beschrijvende naam (bijv. "SAP Equipment Sync")
6. Systeemgebruiker: Koppel een gebruiker voor autorisatie
7. Bedrijf: Selecteer het bedrijf (bij multi-company)
8. Voeg entiteiten toe en configureer properties
9. Sla op -- het API key secret wordt gegenereerd

Systeemgebruiker koppelingbewerken

De gekoppelde systeemgebruiker bepaalt de record-level autorisatie. Als de gebruiker alleen toegang heeft tot afdeling "01", kan de API key ook alleen records van die afdeling ophalen of wijzigen.

Tip: Maak een dedicated systeemgebruiker aan voor elke API key, zodat autorisatie onafhankelijk van persoonlijke accounts kan worden beheerd.

Templatesbewerken

Ultimo biedt voorgedefinieerde API key templates voor veelvoorkomende use cases. Een template bevat de meest relevante entiteiten, properties en filters.

Beschikbare templatesbewerken

Template gebruikenbewerken

1. Selecteer bij het aanmaken van een API key een template
2. De template vult automatisch de entiteiten en properties
3. Pas eventueel aan: voeg properties toe of verwijder overbodige
4. Configureer filters indien nodig

Entiteiten en properties configurerenbewerken

Entiteiten toevoegenbewerken

Per API key kun je meerdere entiteiten toevoegen: - Standaard entiteiten: Equipment, Job, Department, Employee, etc. - Custom entiteiten: Entiteiten die beginnen met _ (bijv. _MijnEntiteit)

Properties per entiteitbewerken

Voor elke entiteit configureer je: - Leesbare properties: Welke velden worden teruggegeven bij GET - Schrijfbare properties: Welke velden mogen worden ingesteld bij PUT/POST/PATCH - Verplichte properties: Minimaal Context en Status bij insert

Filtersbewerken

Beperk de beschikbare data per entiteit met filters: - Filter op Context (bijv. alleen Technical Service assets) - Filter op Status - Filter op Afdeling

Workflows koppelenbewerken

Naast standaard CRUD-operaties kun je workflows koppelen aan een API key:

POST https://customer.ultimo.net/api/v1/action/{workflow-naam}

Workflows maken het mogelijk om: - Complexe bedrijfslogica uit te voeren via de API - Bestandsuploads te verwerken - Meerdere entiteiten in een keer bij te werken - Custom validaties toe te passen

Voorbeeld: File upload workflowbewerken

curl --location "https://customer.ultimo.net/api/v1/action/_REST_UploadFile" \
  --header "applicationelementid: 99999999-9999-9999-9999-999999999999" \
  --header "apikey: abc123def456" \
  --form "File=@C:/temp/Rapport.pdf" \
  --form "JobId=123456789"

Beveiligingbewerken

API Key Secretbewerken

• Het secret wordt eenmalig getoond bij aanmaak
• Bewaar het secret op een veilige locatie
• Deel het secret nooit in client-side applicaties (web/mobile apps)

Veilig gebruikbewerken

IP Filtering (Azure)bewerken

Per API key kan een IP-adres whitelist worden geconfigureerd: - Gebruik - voor bereiken (bijv. 192.168.1.1-192.168.1.255) - Gebruik ; voor meerdere bereiken - Ondersteunt IPv4 en IPv6 - Als slechts een protocol is geconfigureerd, wordt het andere geblokkeerd

Client Certificates (Azure)bewerken

Per API key kan een certificaat-thumbprint worden ingesteld: - Het verbindende systeem moet het bijbehorende certificaat meesturen - Bij certificaatgebruik wijzigt de endpoint URL:

Quota beheerbewerken

Standaard limietenbewerken

Individueel quotumbewerken

Per API key kan een dagelijks quotum worden toegewezen. Dit is nuttig om: - Resources te verdelen over meerdere integratiepartners - Essientiele systemen te beschermen tegen overbelasting - Misbruik van een enkele key te beperken

Meertalige configuratiebewerken

API keys kunnen worden geconfigureerd voor meertalige output: - Meertalig aan: Properties worden teruggegeven als genest object met alle talen - Meertalig uit: Properties worden als enkele waarde teruggegeven

Gebruik de Content-Language header bij schrijfoperaties:

Content-Language: NL

Swagger documentatiebewerken

Ultimo genereert per API key automatisch Swagger documentatie: - Toont alle beschikbare endpoints voor die specifieke key - Bevat interactieve testfunctionaliteit - Documenteert alle entiteiten, properties en workflows

Praktische tips voor consultantsbewerken

1. Een key per systeem: Maak een aparte API key per extern systeem voor traceerbaarheid en onafhankelijk beheer
2. Minimale rechten: Configureer alleen de entiteiten en properties die daadwerkelijk nodig zijn
3. Dedicated gebruiker: Koppel een dedicated systeemgebruiker, niet een persoonlijk account
4. Documenteer: Leg per API key vast waarvoor deze wordt gebruikt, welk systeem de key heeft en wie het aanspreekpunt is
5. Rotatie: Plan periodieke vernieuwing van API key secrets
6. Monitoring: Monitor het dagelijks gebruik via de quota-instellingen

Playgroundbewerken

Ultimo biedt een playground-omgeving voor het testen van API calls:

Gerelateerde artikelenbewerken

• rest-api -- REST API documentatie
• odata-filters -- OData query opties
• Integraties overzicht