Skip to main content
Version: v8xxx

Route network traffic through a proxy

BlinkID processes documents on the device, but it still makes two kinds of network requests:

  • Ping: SDK telemetry, sent to https://ping.microblink.com
  • Baltazar: the online license check, sent to https://baltazar.microblink.com/api/v2/status/check, used only by online licenses

If your app or website may only talk to your own domains, for example because of an egress allowlist, a corporate firewall, or a strict Content Security Policy, you can send both through an HTTPS proxy that you host. The SDK then sends requests to your proxy, and your proxy forwards them to Microblink.

The proxy setting doesn't cover resource downloads or over-the-air (OTA) resource updates. To avoid all communication with Microblink services, also configure resources and OTA updates.

note

Using a proxy requires a special license. To get one, contact us at help.microblink.com.

Set the proxy URL​

Set the proxy URL in the SDK settings when you initialize the SDK. The URL must use HTTPS.

Pass microblinkProxyUrl to createBlinkId.

import { createBlinkId } from "@microblink/blinkid";

const blinkId = await createBlinkId({
  licenseKey: "your-license-key",
  microblinkProxyUrl: "https://your-proxy.example.com",
});

If the URL can't be parsed or doesn't use HTTPS, createBlinkId throws a ProxyUrlValidationError with the code INVALID_PROXY_URL or HTTPS_REQUIRED.

The SDK appends the service paths to the URL you provide, and keeps any path prefix. For example, with https://example.com/mb-proxy the license check goes to https://example.com/mb-proxy/api/v2/status/check. This lets you run the proxy under an existing API gateway.

Avoid resource requests​

Besides the two services above, the SDK loads its resources and resource updates. Depending on your configuration, these requests can go to Microblink services:

  • Initial resources are downloaded from https://models.cdn.microblink.com/resources by default on iOS and Android. On Web, they're loaded from your own host by default.
  • Over-the-air (OTA) resource updates are on by default, and go to https://blinkid-ota.microblink.com on all platforms.

To avoid all requests to Microblink services, load resources from a location you control, and either turn off resource update checks, or point the update service URL to a host you control, such as a mirror or a proxy.

With update checks turned off, the SDK uses the resources it ships with, and resources change only when you update them yourself. This means you don't get support for newly added documents as soon as Microblink releases it. On iOS and Android, download newer resources and ship them in a new release of your app. On Web, replace the resource files on your server.

Host the resources yourself, and don't point resourcesLocation to Microblink's CDN (https://models.cdn.microblink.com/web/...). See Hosting resources.

Turn off update checks with otaResources.checkForUpdates. The SDK then loads the OTA resources from resources/ota-resources/ under the resources location, or from otaResources.resourcesLocation if you set it.

const blinkId = await createBlinkId({
  licenseKey: "your-license-key",
  microblinkProxyUrl: "https://your-proxy.example.com",
  otaResources: {
    checkForUpdates: false,
  },
});

To keep update checks on, set otaResources.otaResourceProviderUrl to an OTA provider that you host or proxy. It must serve the OTA versions API:

GET {otaResourceProviderUrl}/api/v1/versions?generic_version={recognizerVersion}

The response contains links to the resource files, and the SDK downloads the files from those links. The links must also point to hosts you control.

Set up the proxy server​

Your proxy is a reverse proxy that routes requests by path:

  • /api/v2/status/check goes to https://baltazar.microblink.com/api/v2/status/check.
  • /api/v3/ping and /api/v3/ping;multi go to https://ping.microblink.com, with the path unchanged.

Route Ping by the /api/v3/ping path prefix, or forward every path other than /api/v2/status/check to https://ping.microblink.com. A route that only matches /ping doesn't work.

If the proxy runs under a path prefix, strip the prefix and forward the rest of the path.

The proxy must:

  • serve a TLS certificate that your users' devices and browsers trust
  • forward request bodies and the Content-Type header unchanged, without re-encoding, compressing, or batching requests
  • forward ;multi as part of the path, without stripping it, encoding the ;, or treating it as a parameter
  • set the upstream Host header and TLS SNI to the Microblink host, not the proxy host
  • return upstream status codes and response bodies unchanged, so that the SDK can handle license errors

Additional requirements for web​

The web SDK sends requests from a web worker, so they are cross-origin requests to your proxy. The proxy must:

  • answer OPTIONS preflight requests
  • return Access-Control-Allow-Origin with your page's origin, and Access-Control-Allow-Headers: Content-Type

Also add the proxy origin to the connect-src directive of your Content Security Policy.

Example nginx configuration​

server {
    listen 443 ssl;
    server_name your-proxy.example.com;

    ssl_certificate     /etc/ssl/your-proxy.crt;
    ssl_certificate_key /etc/ssl/your-proxy.key;

    # CORS, required for web only
    add_header Access-Control-Allow-Origin  "https://your-app.example.com" always;
    add_header Access-Control-Allow-Methods "POST, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Content-Type" always;
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Methods;
    proxy_hide_header Access-Control-Allow-Headers;
    if ($request_method = OPTIONS) { return 204; }

    location = /api/v2/status/check {
        proxy_pass https://baltazar.microblink.com;
        proxy_set_header Host baltazar.microblink.com;
        proxy_ssl_server_name on;
    }

    location /api/v3/ping {
        proxy_pass https://ping.microblink.com;
        proxy_set_header Host ping.microblink.com;
        proxy_ssl_server_name on;
    }
}

Verify the setup​

  1. Initialize the SDK and confirm that it doesn't return an error.
  2. Check the proxy access log for POST /api/v3/ping requests made during initialization. With an online license, also check for a POST /api/v2/status/check request that returned 200.
  3. In a network inspector, confirm that there are no direct requests to ping.microblink.com or baltazar.microblink.com. If you must avoid all Microblink services, also confirm that there are no requests to models.cdn.microblink.com or blinkid-ota.microblink.com.

Troubleshooting​

  • Initialization fails with "your license doesn't permit proxy usage." Your license doesn't support using a proxy. Contact us at help.microblink.com to get one that does.
  • Initialization fails with a server permission error. The proxy doesn't forward /api/v2/status/check to Baltazar, or it sends the wrong Host header or SNI.
  • Ping requests fail on Android, or the proxy log shows //api/v3/ping. The proxy URL ends with a slash. Remove it.
  • The browser console shows a CORS error. The proxy doesn't answer preflight requests or doesn't return the CORS headers. See Additional requirements for web.
  • A TLS handshake error occurs on mobile. The device doesn't trust the proxy certificate. Use a publicly trusted certificate, or trust your certificate authority in the app configuration.
  • Requests still go to models.cdn.microblink.com or blinkid-ota.microblink.com. The proxy setting doesn't cover resources and OTA updates. See Avoid resource requests.
  • All requests still go directly to Microblink. The proxy URL isn't set when the SDK is initialized, or your SDK version doesn't support it.
Last updated on