Developer

English

Portuguese

English

Portuguese

Appearance

Authentication ​

How to obtain and use the credential of an iPaaS integration.

Each iPaaS integration has a dedicated credential, made up of a Key (clientId) and a Secret (clientSecret). It is created together with the integration and only authorizes running that integration. With this credential you generate an access token and send the token in every execution call.

Obtaining the credential ​

The credential is generated automatically when the integration is created. In the Partner's Portal, the full Secret is only available while the creation wizard is open, in the same browser tab: in the Parameters step (through the eye icon and the copy button) and, at the end of publishing, on the Integration activated successfully screen.

FieldDescription
Key (clientId)Identifier of the credential, in the format integrationhub-{flowId}, where {flowId} is the integration ID (the same one shown in the Endpoint URL).
Secret (clientSecret)Secret of the credential. On the Integration activated successfully screen, it is shown visible, with the copy button. Outside the creation wizard, the portal only shows its beginning and end.

❗️ Attention

Copy the Secret and store it in a safe place before leaving the creation wizard. If you leave the wizard or close the tab before copying it, it cannot be recovered, and you will need to create a new integration.

Editing and publishing an integration again keeps the same Key and Secret: your system does not need to change the credential.

📘 Note

The integration's credential also appears on the API Keys screen, with the Key integrationhub-{flowId}, but it cannot be deleted there: it is removed together with the integration. It differs from a regular API Key because it only runs this integration.

📘 Note

In Product Search there is no credential to copy: the caller of the integration is ME itself. When you publish, the portal shows a confirmation and returns to My Integrations.

Generating the access token ​

Exchange the Key and the Secret for an access token using the POST Generate Token endpoint of the ME authentication API.

http
POST https://api.mercadoe.com/v1/auth/tokens
Content-Type: application/json
json
{
  "clientId": "integrationhub-{flowId}",
  "clientSecret": "{secret}"
}

Response:

FieldDescription
accessTokenToken to be sent in the Authorization header of execution calls.
expiresInToken validity. When the token expires, generate a new one with the same Key and Secret.

See the full response format in Generate Token.

Using the token ​

Send the token in the Authorization header with the Bearer prefix:

http
POST https://api.mercadoe.com/integration-hub-api/v1/flows/{flowId}/execute
Authorization: Bearer {accessToken}
Content-Type: application/json

📘 Note

A token generated with an integration's credential only runs that integration. A call to another integration's Endpoint URL is rejected with 403 Forbidden.

Best practices ​

  • Store the Secret in a secrets vault. Never put it in source code, logs or URLs.
  • Reuse the token while it is valid, instead of generating a new one for every call.
  • Use one integration, and therefore one credential, for each purpose. This way you can revoke or suspend one without affecting the others.