Documentation

Auth - Standalone Integration Guide

Leverage the Auth SDK to seamlessly allow your users to initiate on-chain deposits and withdrawals

Suggest Edits

Pre-integration Steps

1. Create your Organization

Connect will onboard each new Organization in a white-glove manner. Reach out to your rep to get KYB requirements and step-by-step instructions.

2. Configure your Organization

System configurations

  1. Supported assets: See supported assets here.
  2. Transfer methods: You can choose to enable any of the below 3, and within the Centralized Exchanges and Non-custodial wallets bullet each Organization can further modify which Auth integrations will be available your users:
  • Centralized Exchanges
  • Non-custodial Wallets
  • Manual Transfers

3. Transaction limits

The Auth configuration system is flexible and can accommodate many types of limit configurations. Notably, here are the most common:

  • Maximum and Minimum per-transaction limits: Define the smallest and largest allowable amounts (denominated in fiat) for a single transaction. Connect will enforce these limits for each individual transaction request.
  • Maximum daily limits: Set a cap on the total transaction volume allowed per user within a 24-hour period. This helps manage risk and comply with regulatory or internal policy requirements.

3. Webhook configurations

The first step is to provide Connect with the callback URL that Connect will emit event updates to.

4. Organization credentials

At the end of the onboarding process, each Organization will receive the following configuration details required to integrate with Connect:

  • Organization Identifier: A unique identifier generated by Connect, used to identify the Organization within the Connect platform. (ie, 4789efea-e034-4e6f-b8a0-5289aacec427)
  • Connect API Credentials: client_id and secret pair generated by Connect, used by the Organization to authenticate backend requests to Connect APIs
    • client_id: a unique identifier such as 30da17fb-15b2-4723-a63c-0488356e1ed0
    • secret: an encryption key such as 7/7+QhFYOH+yeA3KOxgykbbhvUyaCvIE1Z0oHCTLRoz8LDq3uBshZIrGo94GqMoDZ==

Integration Overview

At a high level, the SDK integration involves the following touchpoints:

1. Organization backend generates access token

The Organization generates an access token using the client_id and secret provided.

2. Organization backend initializes Connect Session

The Organization initiates a Connect Session by making an API call from their backend to Connect’s backend, which returns a jwt token. Connect APIs must be authenticated using jwt tokens generated in step 1 above.

3. Organization frontend initializes Connect Auth SDK

The Organization initializes the Connect Auth SDK by passing the jwt received in Step 2. The SDK automatically renders within the specified HTML container.

4. Organization frontend listens to Auth SDK events

The Organization should appropriately handle events triggered by the Auth SDK to track the user journey, such as connect.closed, connect.deposit.success and connect.deposit.failed.

5. Organization backend listens to Deposit Updates Webhook

The Organization should handle webhook calls sent by the Connect backend to track deposit updates, such as connect.deposit.initiated, connect.deposit.broadcasted, connect.deposit.confirmed and connect.deposit.unexpected.

The Organization should validate the jwt received in the webhooks using JWKs provided by Connect.


Integration Specification

1. Organization presents Connect Auth as a transaction option

You should begin by adding Connect Auth as an available option wherever users initiate crypto transactions - such as deposit or withdrawal screens, or any equivalent interface.

2. Generate an Access Token

Endpoint:

Request body:

{
  "client_id":"30da17fb-15b2-4723-a63c-0488356e1ed0",
  "client_secret":"7/7+QhFYOH+yeA3KOxgykbbhvUyaCvIE1Z0oHCTLRoz8LDq3uBshZIrGo94GqMoDZ=="
}

Response status: 200 OK

{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

3. Initializing a Connect Session

Endpoint: POST /v1/sessions

Request body:

{
  "account": {
    "reference_id": "USER01" // the End User's participant_code that was created via POST /participants/customers/new within zerohash
  },
  "session": {
    "metadata": {  
	// The Organization can send in any metadata that will be performed in subsequent webhook calls for reconciliation purposes
    }
  },
  "scopes": [
    "user:deposit:send" // enum: "user:deposit:send" || "user:withdrawal:send"
  ]
}

Response status: 200 OK

Response body: 

{
  "token": {
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",  
    "expires_in": 3600
  }
}

Decoded jwt:

{
  "iss": "connect",
  "sub": "3dfb9dc0-9c00-4673-bc2e-5024ae62166d", // Account Id
  "iat": "2025-07-24T15:42:07.123456789Z",
  "exp": "2025-07-24T15:42:07.123456789Z",
  "jti": "9b2e0b75-00dc-4f5f-a11b-c48d46b16e15",
  "organization": {
    "id": "4789efea-e034-4e6f-b8a0-5289aacec427"
  },
  "account": {
    // Connect Generated
    "id": "16b0e957-f3fd-41d0-b312-f2ec291de6e4",

    // Unique User Account identifier assigned by the Organization
    "reference_id": "USER01"
  },
  "session": {
    // Connect generated
    "id": "16b0e957-f3fd-41d0-b312-f2ec291de6e4"
  }
}

4. SDK Flow

The Landing Page is the first screen that the user will see. This screen displays the Auth Terms, Privacy Policy, Regulatory Disclosures, and captures explicit consent for the terms of this product:

Menu screen

The Menu screen allows the customer select the Auth integration centralized exchange or non-custodial wallet to link and ultimately pull funds from.

Enter exchange credentials

  • Depending on what is selected, the Auth integration-specific sign-in flow will be triggered. See here for each integration's specific workflow.
  • Regardless of Auth Lite vs. Auth Validate, users will be forced to enter their credentials
  • Only the Auth Validate will we perform the account-matching

Exchange - 2FA

  • Depending on the user's settings at the exchange or wallet, they will be asked to complete some form of 2FA (ie, SMS, Authenticator, Passkey, etc)

Select Asset

zerohash will display your current balances of whichever Auth integration you selected:

Enter amount

The customer will now specify the amount of crypto/stablecoins to deposit:

Review

The customer will be asked to review the details of the deposit:

Auth - 2FA

Depending on the user's exchange configuration, it is typical for user's to be forced to perform another 2FA assertion before any money movement takes place. Example screen:

Deposit processing

The deposit has now been broadcasted on-chain and is en-route to zerohash. The customer can choose to stay on this screen to monitor the progress, or navigate away (navigating away from this screen will not affect the completion of the deposit):

Deposit completed

The deposit has confirmed on-chain, zerohash has sent the Auth Completed webhook and you should be credit the customer's balance on your end:

4. Webhooks

Platforms can receive webhooks that allow you to become aware of certain milestones of the transaction. Get in touch with a zerohash rep to have your callback URL's configured.

Webhook - Deposit initiated

Once a deposit has been initiated, before it's been officially confirmed on-chain, we will send a webhook like so:

{
  "event": "connect.deposit.initiated",
  "deposit": {
    "id": "f2d4a13e-8a52-45e3-9825-b0b18c9a8233",
    "asset": "BTC",
    "network": "bitcoin",
    "amount": "0.013",
    "source": "coinbase",
    "created_at": "2025-07-24T15:42:07.123456789Z",
    "updated_at": "2025-07-24T15:42:07.123456789Z",
    "transaction": null
  },
  "account": {
    // Unique User Account identifier assigned by the Organization
    "reference_id": "USER01"
  },
  "session": {
    // Connect generated
    "id": "16b0e957-f3fd-41d0-b312-f2ec291de6e4",
    "metadata": {
    // metadata received in the session initialization will be here
    }
    }
  }
}

Webhook - Deposit confirmed

Once the transaction has been confirmed on-chain, we will send a webhook like so:

{
  "event": "connect.deposit.confirmed",
  "deposit": {
    "id": "f2d4a13e-8a52-45e3-9825-b0b18c9a8233",
    "asset": "BTC",
    "network": "bitcoin",
    "amount": "0.013",
    "created_at": "2025-07-24T15:42:07.123456789Z",
    "updated_at": "2025-07-24T15:35:00.123456789Z",
    "transaction": {
      "hash": "0xf3b9c88212d7a8d611d6f97a4b6e96b2b2c1b7...",
      "block_number": "2025-07-24T15:42:07.123456789Z",
      "timestamp": "2025-07-24T15:42:07.123456789Z",
      "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "to": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
      "value": "1000000000000000000",
      "gas": 21000,
      "gas_price": "30000000000",
      "nonce": 102,
      "input": "0x",
      "status": "0x1",
      "gas_used": 21000,
      "cumulative_gas_used": 105000
    }
  },
  "account": {
    "reference_id": "USER01"
  },
  "session": {
    "id": "16b0e957-f3fd-41d0-b312-f2ec291de6e4",
    "created_at": "2025-07-24T15:42:07.123456789Z",
    "metadata": {
    // metadata received in the session initialization will be here
    }
  }
}

Webhook - Balance update

On the zerohash side, you will also receive a Balance update webhook, indicating that the zerohash ledger has been officially updated as well.


https://docs.zerohash.com/docs/auth-network

See full list of Auth Integrations →

Updated 20 minutes ago