Open API toegang en sleutels

Voordat je begint

De Open API is versie 1. De base URL is https://app.e-tailize.eu/public/api/v1, hij spreekt alleen JSON, en de lijst met endpoints en alle request- en responsevormen staat in Swagger op https://app.e-tailize.eu/swagger/index.html.

Toegang bestaat uit twee lagen. Je client, het bedrijf of de integratie die ons aanroept, wordt één keer goedgekeurd door e-tailize en meldt zich met de header X-Api-ClientId op de endpoints van Auth. Een sleutelpaar hoort bij een gebruiker van een e-tailize account, en de endpoints Connections en Products lezen dat paar uit de headers X-Api-Key en X-Api-Secret, allebei verplicht.

Een Open API sleutel maak je met aanroepen van de API, dus je hebt een tool nodig die verzoeken via HTTP kan sturen en een veilige plek voor een secret.

Stappen

1. Stuur POST /Auth/request-access zonder header met credentials, met je bedrijfsnaam, contactadres, partnernaam en de reden van je aanvraag. Het antwoord bevat je client id en de status Pending.

2. Bewaar dat client id en stuur het mee als header X-Api-ClientId bij elke andere aanroep van Auth.

3. Wacht tot e-tailize je client goedkeurt. Het goedkeuren van een client is een stap aan onze kant en we laten het je weten.

4. Stuur POST /Auth/generate met de gegevens van de gebruiker bij wie de sleutel hoort. Het antwoord bevat de sleutel, het secret en de vervaldatum van de sleutel.

5. Zet het secret in je eigen kluis voordat je het antwoord sluit.

6. Controleer het paar met POST /Auth/validate/{apiKey}: de sleutel in het pad, het secret in de body en niet in een header.

7. Stuur X-Api-Key en X-Api-Secret bij elke aanroep van Connections en Products, samen met Accept: */*.

Wat er daarna gebeurt

Het paar draagt het account en het project van de gebruiker waarvoor het is gemaakt, dus je aanroepen lezen en schrijven de gegevens die deze gebruiker ook in de app ziet.

POST /Auth/generate geeft je de sleutel terug die je al hebt, zonder secret in de body, dus roteren is eerst intrekken en dan opnieuw maken: POST /Auth/revoke/{apiKey} gooit het paar weg, POST /Auth/generate geeft je een nieuw paar. Bewaar de vervaldatum uit het antwoord op generate en roteer op tijd.

Bouw je voor een klant van ons? POST /Auth/generate/by-project-and-tenant zet de sleutel vast op één project van één klantaccount in plaats van op dat van jezelf.

Veelvoorkomende problemen

Een 400 waar je een 401 verwachtte. Een header met credentials die ontbreekt of niet goed is gevormd, geeft 400. Kijk dus of X-Api-Key en X-Api-Secret allebei meegaan.

Een 401 betekent dat de headers wel goed zijn gevormd maar niet worden geaccepteerd: de client is niet goedgekeurd, de sleutel of het secret klopt niet, de sleutel is verlopen, of de eigenaar van de sleutel is niet goedgekeurd.

Een 406 in plaats van een leesbare fout. Fouten komen terug als application/problem+json, dus een client die om Accept: application/json vraagt, ziet de echte melding nooit. Stuur Accept: */*.

Geeft POST /Auth/validate/{apiKey} een 400 met "Invalid or unapproved api key and secret", dan dekt die melding vier gevallen tegelijk: onbekende sleutel, verkeerd secret, verlopen sleutel, of een gebruiker die niet is goedgekeurd.

Een aanvraag die wordt geweigerd op het contactadres. Eén contactadres hoort bij één client, en een aanvraag die is goedgekeurd of afgewezen kan niet nog een keer worden ingediend.

Veelgestelde vragen

Waar vind ik mijn sleutel in de app?

Open API sleutels beheer je met aanroepen van de API, niet via een scherm: een sleutel bestaat in het antwoord op POST /Auth/generate en in de kluis waar je hem hebt gezet. Gebruikers en hun rollen zijn een ander onderwerp, zie Voeg gebruikers toe en beheer hun rollen.

Kan één gebruiker twee sleutels tegelijk hebben?

Nee. Een gebruiker heeft een actieve sleutel tegelijk, dus POST /Auth/generate weigert een tweede actieve sleutel en antwoordt met 200 en de sleutel die je al hebt, zonder secret in de body. Daarom is roteren eerst POST /Auth/revoke/{apiKey} en daarna generate.

Hoe ziet een foutmelding eruit?

Elke fout heeft dezelfde drie velden: title, status en errors. In errors staan de veldnamen die fout gingen, in camelCase, of de sleutel general als het probleem niet over één veld gaat. Er is geen detail, instance of traceId om te lezen.

Gerelateerd

• Open API endpoints en limieten
• Voeg gebruikers toe en beheer hun rollen
• Een koppeling aanpassen, opnieuw opslaan of verwijderen