Ctrl+K

Activate Client Connections

Overview

Clients can connect their Go Network account to their account on your platform. When clients initiate linking their accounts, BitGo sends you a connection request with a connection ID and a client ID.

Clients can create multiple connections to your platform. However you must validate that the client account associated with an API key is a new account with no existing assets. Ensure that you create only 1 connection per client account.

Before sending your platform a connection request, BitGo verifies the authentication using secure session or long-lived access tokens.

Prerequisites

  • Get Started - Ensure your access token has the following permissions:
    • Settlement Network - Read
    • Settlement Network - Write

API Specification

Use the following to build an endpoint that BitGo can send requests to for processing connections.

Route: POST /bitgo/v1/connections

This endpoint must:

  • This endpoint must take a connectionId in the event of a retry, so that you don't act on the same connection twice.
  • The endpoint must be idempotent and return the existing connection if the requested connection already exists.
  • You can only create 1 connection per account on your platform.
  • BitGo users may create multiple connections to your network, however you must validate that the account tied to the connectionId is a new account. On your system, a network connection should be 1-to-1 with a partner user account. A network client is 1-to-many with partner user accounts.

Request Headers

HeaderTypeDescription
X-BitGo-SignaturestringThe signature BitGo provides using a private/public key pair.

Request Body

ParameterTypeDescription
clientIdUUIDThe BitGo ID for the user on your system.
clientWalletIdstringThe ID of the user’s Bitgo wallet.
connectionIdUUIDThe ID of the connection.
connectionTokenstringAn OTP or unique identifier designed for identification of the user by you.
partnerIdUUIDThe ID of your partner account that the connection is tied to.

200 Response

Response FieldTypeDescription
clientIdUUIDThe BitGo ID for the user on your system.
connectionIdUUIDThe ID of the connection.
partnersClientIdstringThe ID of the user in your system.
partnersConnectionIdstringThe ID of your partner account that the connection is tied to.

400/401/409/500 Response

Response FieldTypeDescription
errorstringA description of the error.

Request Verification

When you receive a request from BitGo, you must verify the authenticity of the request. Once the request is verified as an authentic BitGo request, you must verify the authenticity of the connection token before initiating the connection between the client’s BitGo account and the client’s account on your platform.

1. Activate Client Connection

BitGo sends you the following request for each client-initiated connection:

  • API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
POST /bitgo/v1/connections

Request Headers
{
    "X-BitGo-Signature": "string"
}

Request Body
{
    "clientId": "UUID",
    "connectionId": "UUID",
    "connectionToken": "string", // connectionToken can be an OTP or unique identifier
    "PartnerId": "UUID",
}

Your system sends the following response:

  • JSON
1
2
3
4
5
6
{
    "clientId": "UUID",
    "connectionId": "UUID",
    "partnersClientId": "string",
    "partnersConnectionId": "string"
}

Next

Allocate Assets