# Activate Client Connections

Source: https://developers.bitgo.com/docs/oes-partner-connect

## 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](/docs/get-started-access-tokens).

## Prerequisites

* [Get Started](/docs/get-started-intro) - Ensure your access token has the following permissions:
    * `Settlement Network - Read`
    * `Settlement Network - Write`

## Cookbook

Need just the steps? Expand the cookbook below to get started:

<Cookbook slug="oes-partner-connect" title="Activate Client Connections" />

## 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

| Header | Type | Description |
| :---- | :---- | :---- |
| `X-BitGo-Signature` | string | The signature BitGo provides using a private/public key pair. |

### Request Body

| Parameter | Type | Description |
| :---- | :---- | :---- |
| `clientId` | UUID | The BitGo ID for the user on your system. |
| `clientWalletId` | string | The ID of the user’s BitGo wallet. |
| `connectionId` | UUID | The ID of the connection. |
| `connectionToken` | string | An OTP or unique identifier designed for identification of the user by you. |
| `partnerId` | UUID | The ID of the partner the client is attempting to create a connection to. |

### 200 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| `clientId` | UUID | The BitGo ID for the user on your system. |
| `connectionId` | UUID | The ID of the connection. |
| `partnersClientId` | string | The ID of the user in your system. |
| `partnersConnectionId` | string | The ID of your partner account tied to the connection. |

### 400/401/409/500 Response

| Response Field | Type | Description |
| :---- | :---- | :---- |
| error | string | A description of the error. |

## Request Verification

When you receive a request from BitGo, you must [verify the authenticity of the request](/docs/oes-partner-signature). Once you verify the request as an authentic BitGo request, you must verify the authenticity of the connection token. After verifying the token, initiate 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:

```json API
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 JSON
{
    "clientId": "UUID",
    "connectionId": "UUID",
    "partnersClientId": "string",
    "partnersConnectionId": "string"
}
```

## Next

[Allocate Assets](/docs/oes-partner-allocate)