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.