Keychain Proxy

Keychain is a Mergado service that stores and manages user credentials for third-party platforms (e.g. Heureka, Google Analytics, Shopify). It acts as a secure credential store — apps never handle credentials directly, but instead access external services through the Mergado proxy, which attaches the stored credentials automatically. This document describes how to use the Keychain proxy in your app.

How It Works

The app never handles user credentials directly. Instead, the user stores credentials for a third-party service in their Keychain, and the app communicates with that service through the Mergado proxy.

The flow for every proxied request is:

1. The user saves their credentials for a third-party service into their Keychain.
2. The app calls the proxy endpoint on Mergado.
3. Mergado attaches the stored credentials to the outgoing request.
4. The request is forwarded to the target service.
5. The response is returned to the app.

App                    Mergado Proxy              Target Service
 |                           |                           |
 |-- proxy request --------->|                           |
 |                           |-- attach credentials ---->|
 |                           |<-- response --------------|
 |<-- response --------------|                           |

Using the Proxy in Your App

The general implementation flow is:

1. Check whether the user has a connection for the required service. Call the shop info endpoint (see API documentation) and inspect the returned connections.
2. If no connection exists — redirect the user to Keychain so they can create one.
3. If a connection exists — call the appropriate proxy endpoint for the service. The full list of available services and proxy endpoint patterns is in the API documentation.

The app never has access to the user’s credentials at any point — the proxy layer handles authentication transparently.

Validating a Connection

To check the current status of a specific Keychain connection, use the validate endpoint.

The response contains:

• is_valid — whether the connection is currently functional. Can be null when the validation itself cannot be completed (e.g. the external service is experiencing an outage or behaving unexpectedly).
• errors — an array of error objects with an error code and a human-readable message when is_valid is false.

Webhooks

Mergado notifies your app via webhooks when the state of a Keychain connection changes — for example when a user creates or removes a connection. This allows your app to react without polling.

The relevant hooks are control.shop.keychain.link_created and control.shop.keychain.link_deleted. Their payloads and full documentation are in the Hooks documentation.

Note: You can manage your app’s hook URL via your app’s Storage page in Developers.

Error Handling

Apps should assume that an existing Keychain connection is functional. When a proxy call fails, the recommended approach is:

1. On proxy error — call the validate endpoint to check the connection status.
2. If the connection is invalid — store the invalid state locally and stop making proxy calls. Wait for a control.shop.keychain.link_created webhook indicating the user has reconnected.
3. Periodic re-check — as a safety net (in case a webhook is lost or a temporary outage self-resolved), re-validate the connection periodically with a long interval (every few hours or once a day) for some time after the invalidation.
4. Delay user notifications — notify the user only after a re-validation attempt confirms the connection is still broken, to avoid false alarms caused by transient failures.