Creating Share Tokens

Source Organizations can create Share Tokens to share end user data with data sharing partners (Destination Organizations). Destination Organizations can use Share Tokens to copy and verify the end user’s data.

Source Organizations can create Share Tokens via API, Dashboard, or Workflows.

Creating Share Tokens via API

To create a Share Token via API, the Source Organization provides the Connection ID and a Source ID. The connection-id specifies which partner organization can access the specified source-id, and only that partner organization is able to redeem the created Share Token. The source-id can be an Inquiry, Transaction, or Account ID (e.g., inq_ABC123, txn_ABC123, or act_ABC123).

$
curl -X POST https://api.withpersona.com/api/v1/connect/share-tokens \
>
  -H "Authorization: Bearer <token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "data": {
>
      "attributes": {
>
        "connection-id": "cxn_ABC123",
>
        "source-id": "inq_ABC123"
>
      }
>
    }
>
  }'

1
{
2
  "data": {
3
    "type": "connect/share-token",
4
    "id": "cnst_ABC123",
5
    "attributes": {
6
      "status": "created",
7
      "direction": "outbound",
8
      "created-at": "2023-08-17T23:18:13.000Z",
9
      "updated-at": "2023-08-17T23:18:13.000Z",
10
      "expires-at": "2023-08-31T23:18:13.000Z"
11
    },
12
    "relationships": {
13
      "connection": {
14
        "data": {
15
          "type": "connect/connection",
16
          "id": "cxn_ABC123"
17
        }
18
      },
19
      "creator": {
20
        "data": {
21
          "type": "user",
22
          "id": "user_ABC123"
23
        }
24
      },
25
      "source": {
26
        "data": {
27
          "type": "inquiry",
28
          "id": "inq_ABC123"
29
        }
30
      }
31
    }
32
  }
33
}

Creating Share Tokens via Dashboard

Source Organizations can also create Share Tokens using their Dashboard under the Connect > Share Tokens page. This can be helpful for testing and one-off data shares. Creating the Share Token requires selecting a Connection and providing a Source ID (an Inquiry, Transaction, or Account ID). Only the specified Destination Organization will be able to redeem the Share Token.

Creating Share Tokens via Workflows

Source Organizations can use Workflows to automate Share Token creation. For example, the Source Organization can use a Workflow to automatically create a Share Token upon Inquiry completion. Similarly, the Destination Organization can use a Workflow to automatically redeem the created Share Token. This can be helpful for integrating into Connect with minimal development work.

Sending Share Tokens to Destination Organizations

After creating a Share Token, the Source Organization can send it to the Destination Organization using the Destination Organization’s API or SDK, or another secure channel. Alternatively, the Destination Organization can use a Workflow to automatically get notified about and redeem Share Tokens when they are created.

Outbound Share Token Events

Source Organizations receive the following events related to Share Tokens. These events can be used to trigger Webhooks and Workflows.

• connect/share-token.outbound-created — Occurs in the Source Organization when it creates a Share Token for a Destination Organization. Use this event to confirm creation and notify downstream systems.
• connect/share-token.outbound-redeemed — Occurs in the Source Organization when the Destination Organization’s Share Token redemption has finished. At this point, the Share Token’s status is redeemed.