User Pre-Authorization

This section covers two approaches for authenticating users from your backend. Silent Authentication pre-authorizes users before they open the widget — they skip the login step entirely. API-Based Authentication is used exclusively for the Submit Documents KYC flow and does not authenticate users in the widget.

Silent Authentication

Silent authentication lets your users skip the login step in the widget by passing a short-lived token in the URL. Mercuryo handles the authentication on its end — no user credentials are shared with you.

Before using silent authentication, you must obtain the user's consent to Mercuryo's Terms of Service on your side.

All endpoints below require the Sdk-Partner-Token header. Contact your integration manager to obtain it.

Silent Sign-Up

For users who don't have a Mercuryo account yet.

Endpoint: POST /v1.6/sdk-partner/sign-up

Required body parameters:

• email — user's email address
• accept — user's consent to the Terms of Service (you collect this on your frontend)

Optional parameters:

• language_code — default: en-US
• share_token — SumSub token for pre-verified KYC (see KYC)

Response includes:

• init_token — widget sign-in token (valid for 1 hour or until first widget visit)
• init_token_type — always sdk_partner_authorization
• user_uuid — user's Mercuryo UUID

Steps:

1. Call POST /v1.6/sdk-partner/sign-up to get init_token and init_token_type.
2. Pass these as URL parameters when redirecting the user to the widget.
3. Show your widget.

https://exchange.mercuryo.io/?widget_id=YOUR_WIDGET_ID
  &init_token_type=sdk_partner_authorization
  &init_token=0a25dd714163a9006

Silent Sign-Up + SumSub KYC

For users who already have a verified KYC on your SumSub instance.

Same as Sign-Up but also include share_token in the request body:

POST /v1.6/sdk-partner/sign-up
{
  "email": "user@example.com",
  "accept": true,
  "share_token": "_act-ca0dae00-0ecd-000d-00e0-00d0ca000b0d"
}

Widget URL with both tokens:

https://exchange.mercuryo.io/?widget_id=YOUR_WIDGET_ID
  &init_token_type=sdk_partner_authorization
  &init_token=0a25dd714163a9006
  &share_token=_act-ca0dae00-0ecd-000d-00e0-00d0ca000b0d

Silent Sign-In

For users who already have a Mercuryo account.

Endpoint: POST /v1.6/sdk-partner/login

Identify the user by one of:

• email
• phone
• user_uuid4

Response includes:

• init_token
• init_token_type
• user_uuid

Steps:

1. Call POST /v1.6/sdk-partner/login to get init_token and init_token_type.
2. Pass them as URL parameters.
3. Show your widget.

https://exchange.mercuryo.io/?widget_id=YOUR_WIDGET_ID
  &init_token_type=sdk_partner_authorization
  &init_token=0a25dd714163a9006

API-Based Authentication

This approach uses API calls to authenticate users. Unlike silent authentication, user information is shared with you during the process.

Each API request must include one of two tokens in the header:

Sdk-User-Token is returned as bearer_token in the sign-in response. It expires in 24 hours in Production and does not expire in Sandbox.

Before signing up, the user must accept the Terms of Service on your frontend. Pass their consent in the accept parameter.

OTP-less Sign-In

Use when you have already verified the user's email and identity on your side, and no additional verification is required.

1. Obtain Sdk-Partner-Token from your integration manager.
2. Call POST /v1.6/sdk-partner/user/sign-in-no-verify with the user's email.

Sign-In with OTP Verification

Use when the user must verify their email via a one-time code.

1. Obtain Sdk-Partner-Token from your integration manager.
2. Call POST /v1.6/sdk-partner/user/sign-in with the user's email. An OTP is sent to the user.
3. Call POST /v1.6/sdk-partner/user/sign-in/verify with the OTP entered by the user.
   • To resend the OTP: POST /v1.6/sdk-partner/user/sign-in/verify/resend