Share Links

Share links let you connect a single Taufinity Studio capability, a playbook or a dashboard, to an external caller without sharing an API key. Hand someone a link; they get access to exactly that one thing, nothing more.

Typical uses:

• Pull dashboard data into Google Sheets with =IMPORTDATA
• Run an AI playbook on Sheets cell values in real time
• Process a column of rows through a playbook with Google Apps Script
• Send requests from Zapier, Make, or any webhook-capable tool

How it works

Each share link is an AES-256-GCM encrypted URL. The encrypted payload carries the target endpoint, the allowed HTTP method, your organization context, and an optional set of locked parameters, values the caller cannot override. No credentials appear in the URL.

Share links are rate-limited, self-expiring, and revocable at any time.

---

Create a share link

Open Settings → API Keys in Studio and click New Share Link, or use the API directly.

Via the UI

1. Go to Settings → API Keys → Share Links tab
2. Click New share link
3. Choose a template (see table below)
4. Pick the resource (which playbook or dashboard)
5. Optionally pin filter values that callers cannot change
6. Click Generate

Copy the URL from the result. This is the only time the raw token is shown in full.

Via the API

curl -s -X POST https://studio.taufinity.io/api/admin/share-links \
  -H "X-API-Key: YOUR_ADMIN_KEY" \
  -H "X-Organization-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "playbook:trigger-get",
    "vars": { "playbook_id": "46" },
    "name": "Plant lookup, Sheets"
  }'

Response 201 Created:

{
  "key": {
    "id": 42,
    "key_prefix": "3f7a91c0",
    "name": "Plant lookup, Sheets",
    "expires_at": "2026-08-17T12:00:00Z"
  },
  "url": "https://studio.taufinity.io/s/eyJhbGci...",
  "importdata_formula": "=IMPORTDATA(\"https://studio.taufinity.io/s/eyJhbGci...\")"
}

---

Templates

Choose a template when creating a share link. Each template fixes the endpoint and HTTP method; you only supply the resource.

Template	Method	Best for	Rate limit	Expiry
dashboard:csv	GET	Pull dashboard data into Sheets via =IMPORTDATA	60/h	90 days
playbook:trigger-get	GET	Run a playbook on a Sheets cell value via =IMPORTDATA	600/h	90 days
playbook:trigger	POST	Run a playbook from Apps Script, Zapier, or a webhook	30/h	90 days
playbook:batch	POST	Process 100+ rows through a playbook in one request	60/h	90 days

---

Google Sheets recipes

Pull dashboard data (read-only)

Use dashboard:csv to load live report data into a sheet.

1. Create a share link with template dashboard:csv and your dashboard's slug
2. In Google Sheets, paste the returned URL into any cell:

=IMPORTDATA("https://studio.taufinity.io/s/eyJhbGci...")

The sheet refreshes automatically. To pin the data to a specific client or date range, set optional locks when creating the link, the caller cannot override locked parameters.

Optional locks for dashboard:csv:

Parameter	What it pins
client_name	Restricts data to one client
region	Restricts to a region
from	Earliest date (YYYY-MM-DD)
to	Latest date (YYYY-MM-DD)
group_by	Grouping dimension

---

Run a playbook on each row

Use playbook:trigger-get to process a column of cell values through an AI playbook. Each cell value is passed as ?input= and the playbook result comes back as plain text.

Playbook requirement

The playbook must have Allow GET trigger enabled. Enable it in Playbooks → Edit → Advanced.

1. Create a share link with template playbook:trigger-get and the playbook ID
2. The API returns an importdata_formula: a base formula without the input. Append &input="&ENCODEURL(A2) to hook it to a cell:

=IMPORTDATA("https://studio.taufinity.io/s/eyJhbGci...&input="&ENCODEURL(A2))

3. Put this formula in cell B2, type your input in A2, and drag B2 down to process the whole column.

Rate limit

playbook:trigger-get has a 600 req/h limit, the highest of any template, to handle Sheets recalculation bursts when you drag formulas down a large column.

---

Batch-process rows with Apps Script

Use playbook:batch when you have 100+ rows and want to process them efficiently in one call.

Playbook requirement

The playbook must have Allow batch input enabled. Enable it in Playbooks → Edit → Advanced.

function runBatch() {
  const url = "https://studio.taufinity.io/s/eyJhbGci..."; // your batch share link
  const inputs = SpreadsheetApp.getActiveSheet()
    .getRange("A2:A101")
    .getValues()
    .map(([v]) => String(v).trim())
    .filter(Boolean);

  const res = UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json",
    payload: JSON.stringify(inputs),
  });

  const results = JSON.parse(res.getContentText());
  const out = results.map((r) => [r]);
  SpreadsheetApp.getActiveSheet().getRange(2, 2, out.length, 1).setValues(out);
}

---

Single-cell lookup with Apps Script

Use playbook:trigger when you need full control over the request from Apps Script.

function lookupPlant(input) {
  const url = "https://studio.taufinity.io/s/eyJhbGci..."; // your POST share link
  const res = UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json",
    payload: JSON.stringify({ input }),
  });
  return res.getContentText();
}

Use it as a custom formula: =lookupPlant(A2).

---

Revoke a share link

Go to Settings → API Keys, find the share link by name, and click Revoke. The link stops working immediately.

To revoke via the API:

# The JTI is {key_prefix}-{id_in_base36}
# Python computes base-36 from the numeric ID in the creation response
KEY_PREFIX="3f7a91c0"
KEY_ID=42

ID_B36=$(echo "$KEY_ID" | python3 -c "
import sys
n = int(sys.stdin.read())
a = '0123456789abcdefghijklmnopqrstuvwxyz'
s = ''
while n:
    s = a[n % 36] + s
    n //= 36
print(s or '0')
")

curl -s -X DELETE \
  "https://studio.taufinity.io/api/admin/share-links/${KEY_PREFIX}-${ID_B36}" \
  -H "X-API-Key: YOUR_ADMIN_KEY" \
  -H "X-Organization-ID: YOUR_ORG_ID"

Returns 204 No Content. After revocation, any call to the share link returns 401 share link revoked.

---

Expiry and rotation

Links expire at the expires_at date (default 90 days). To rotate without downtime:

1. Create a new share link
2. Update your integrations to use the new URL
3. Revoke the old link once all callers have switched

There is no silent auto-renewal, callers must use the new URL.

---

Security model

Property	Detail
Encryption	AES-256-GCM, URL contains no plaintext credential
Scope	One endpoint, one resource, one organization
Caller isolation	Locked parameters cannot be changed by the caller
Revocable	Revocation list checked on every request
Rate-limited	Per-link limit; 429 on excess with retry-after guidance
GDPR	Encrypted at rest, stored in EU (Netherlands)

A share link cannot be used to access other organizations, other resources, or any endpoint not specified at creation time. Callers observe only the response payload. They cannot read your organization's other data.