> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpersona.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server.

# Creating Share Tokens

Source Organizations can create Share Tokens to share their KYC/KYB data with Destination Organizations. Destination Organizations can redeem Share Tokens to import the data and, as needed, run additional Verifications and Reports.

Customers can create Share Tokens from Inquiries, Transactions, Accounts, or Verifications. They can do so 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, Account, or Verification ID (e.g., `inq_ABC123`, `txn_ABC123`, `act_ABC123`, or `ver_ABC123`).

**`Create a Share Token`**

```bash title="Create a Share Token"
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"
      }
    }
  }'
```

**`Share Token`**

```json title="Share Token"
{
  "data": {
    "type": "connect/share-token",
    "id": "cnst_ABC123",
    "attributes": {
      "status": "created",
      "direction": "outbound",
      "created-at": "2023-08-17T23:18:13.000Z",
      "updated-at": "2023-08-17T23:18:13.000Z",
      "expires-at": "2023-08-31T23:18:13.000Z"
    },
    "relationships": {
      "connection": {
        "data": {
          "type": "connect/connection",
          "id": "cxn_ABC123"
        }
      },
      "creator": {
        "data": {
          "type": "user",
          "id": "user_ABC123"
        }
      },
      "source": {
        "data": {
          "type": "inquiry",
          "id": "inq_ABC123"
        }
      }
    }
  }
}
```

> **Note**
>
> Use `expires-in-seconds` to set a TTL for Share Tokens, between 1 minute and
> 21 days. When omitted, Share Tokens default to expiring 14 days after
> creation.

---

## 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, Account, or Verification ID). Only the specified Destination Organization will be able to redeem the Share Token.

![Persona Dashboard form for creating a Share Token](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/connect-create-share-token-dashboard.png)

---

## Expiring Share Tokens

Share Tokens with a TTL expire automatically when their `expires-at` time passes (see [Setting a TTL](#creating-share-tokens-via-api)). The Source Organization can also expire a Share Token early via API, moving it to `expired` status so it can no longer be redeemed.

**`Expire a Share Token`**

```bash title="Expire a Share Token"
curl -X POST https://api.withpersona.com/api/v1/connect/share-tokens/cnst_ABC123/expire \
  -H "Authorization: Bearer <token>"
```

Only the Source Organization can expire a Share Token early.

---

## Creating Share Tokens via Workflows

Source Organizations can use [Workflows](../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.

![Workflow action that creates a Share Token](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/connect-create-share-token-workflow.png)

---

## 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](/webhooks) and [Workflows](/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`.