Developers

Authorization flows

Before you can use Inbenta APIs, your integrations must obtain an access_token through the Auth API. This access_token is what allows an integration to perform authorized requests to any other API. To obtain an access_token, follow one of the flows below.

 
Important

Remember that each flow has its own security implications.

API Secret Flow

This is designed to fit server side integrations and sensitive front-end integrations.

The process goes like this:

  1. In the server, perform a request including the API Secret to the Auth API /auth endpoint. You can find the Secret in the Administration tab of your Inbenta App.
  2. If the request is valid, the Auth API returns an access_token that allows you to perform requests against the other APIs.
  3. From that moment, you can use the access_token on the server side or the client side, until it expires.
    • You can refresh the token from client side or server side before it expires. If the token expires without refreshing (e.g. if the computer enters sleep mode), you must start the process again.

Security Concerns

 
Important

You must never expose the secret to a client side location. Always keep it server side. For all intents and purposes, you must treat them as passwords.

When used properly, the Secret flow is the most robust option from a security perspective. Because the Secret is never exposed, an attacker will never be able to obtain an access_token. In addition, if you only use the access_token server side, a would-be attacker would not even be able to send a single request to your API instance.

API Domain Key Flow

This is designed to fit client-side integrations with light security requirements.

Domain keys help you integrate Inbenta in your website faster than if you use a Secret, because they do not require a server. However, this flow is also less secure.

The process goes like this:

  1. From the browser (preferably using the SDKs provided by Inbenta), perform a request to the /auth endpoint of the Auth API.
  2. If the request is valid, the Auth API returns an access_token that allows you to perform requests against the other APIs.
  3. From that moment, you can use the access_token on the client side to perform requests against the Inbenta APIs.

Security Concerns

 
Important

Remember that the domain key is always visible to any end users.

Domain keys offer one single restriction: they can only be used for a list of valid domains. However this is only true when the requests come from browsers that include the domain automatically, without the possibility of overriding this value. Any current browser includes this feature.

This means that domain keys can prevent an attacker from creating a website that can spoof your own integration (for phishing, unfair competition or any other malicious intentions), but it does not prevent a user from sending requests to your API instance. 

In summary, any end user with access to the integration could read the domain key and use it to request your API instance outside of a browser. This is why it is possible to revoke domain keys.