On this page
Before you start
The Open API is version 1. Its base URL is https://app.e-tailize.eu/public/api/v1, it
speaks JSON only, and the endpoint list with every request and response shape sits in
Swagger at https://app.e-tailize.eu/swagger/index.html.
Access has two layers. Your client, the company or integration that calls us, is approved
once by e-tailize and identifies itself with the X-Api-ClientId header on the Auth
endpoints. A key pair belongs to a user of an e-tailize account, and the Connections and
Products endpoints read it from the X-Api-Key and X-Api-Secret headers, both of them
required.
You create an Open API key with API calls, so you need a tool that can send HTTP requests and a safe place to keep a secret.
Steps
Send
POST /Auth/request-accesswithout a credential header, with your company name, contact e-mail address, partner name and the reason for the request. The response carries your client id and the statusPending.Store that client id and send it as the
X-Api-ClientIdheader on every other Auth call.Wait for e-tailize to approve your client. Approving a client is a step on our side and we let you know.
Send
POST /Auth/generatewith the details of the user the key belongs to. The response carries the key, the secret and the expiry date of the key.Copy the secret into your own secret store before you close the response.
Check the pair with
POST /Auth/validate/{apiKey}: the key goes in the path, the secret in the body and not in a header.Send
X-Api-KeyandX-Api-Secreton every Connections and Products call, together withAccept: */*.
What happens next
The pair carries the account and the project of the user it was generated for, so your calls read and write the data that user sees in the app.
POST /Auth/generate hands back the key you already have, without a
secret in the body, so rotating means revoking first and generating second:
POST /Auth/revoke/{apiKey} throws the pair away, POST /Auth/generate hands you a new one.
Keep the expiry date from the generate answer and rotate before it passes.
Building for a customer of ours? POST /Auth/generate/by-project-and-tenant pins the key to
one project of one customer account instead of your own.
Common problems
A 400 where you expected 401. A credential header that is missing or malformed answers 400,
so check that both X-Api-Key and X-Api-Secret are on the request.
A 401 means the headers arrived in the right shape but were not accepted: the client is not approved, the key or the secret is wrong, the key expired, or the owner of the key is not approved.
A 406 instead of a readable error. Errors come back as application/problem+json, so a
client that asks for Accept: application/json never sees the real message. Send
Accept: */* instead.
POST /Auth/validate/{apiKey} answering 400 with "Invalid or unapproved api key and secret"
covers four cases at once: unknown key, wrong secret, expired key, or a user who is not
approved.
An access request refused on the e-mail address. One contact address belongs to one client, and a request that was approved or rejected cannot be sent in again.
FAQ
Where do I find my key in the app?
You manage Open API keys with API calls, not in a screen: a key exists in the answer to
POST /Auth/generate and in the store you put it in. Users and their roles are a different
subject, see Add users and manage their roles.
Can one user hold two keys at the same time?
No. A user holds one active key at a time, so POST /Auth/generate refuses a second active
key and answers 200 with the key you already have, without a secret in the body. That is why
rotating is POST /Auth/revoke/{apiKey} first and generate second.
What does an error body look like?
Every error carries the same three fields: title, status and errors. errors holds
the field names that went wrong, in camelCase, or the key general when the problem is not
about one field. There is no detail, instance or traceId to read.
Related
Was this useful?