---
title: "Mint a share link that resumes a connect flow from a server-side prefill"
method: POST
path: "/sharing/connect"
tags: ["Sharing"]
---

# Mint a share link that resumes a connect flow from a server-side prefill

`POST /sharing/connect`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/sharing/connect`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

**Forward-to-a-colleague.** The widget posts the domain(s) a teammate should connect plus an arbitrary `prefill` (the widget config to resume); the control plane stores that server-side under an opaque token and returns the absolute `link` (ends `/share/{token}`) and a `job_id`. Every domain the link targets must be one the calling token may act on: a share link never widens a domain-bound token's reach. The link's server-side prefill is read back by `GET /share/{token}`, which the teammate's widget bootstraps from instead of a URL that carries the config in the clear. The share token EXPIRES 30 days after it is minted.

**Share by email.** With `recipient_email`, CustomDomain™ also emails the link to that address together with the DNS records the domain needs (the records of this application's connection for it when one exists, otherwise the default set) and your optional `note`. The email names the application as the product that asked. A malformed address is a `400` `invalid_request`; so is `recipient_email` without a `domain` or `domains`. Sending is capped at 3 emails per domain per application and 50 per application every 24 hours, and 10 per client IP address per hour; over any cap the call is a `429` `rate_limited` and no link is minted. When the email cannot be sent the link is still returned, with `email_error: "not_sent"`, so the widget can offer to copy it instead.

**From a server.** An API key mints a link for `application_id` (an application in the key's tenant, 404 otherwise) or for the key's own application, and the teammate's flow then connects the domain into that application. A member's key needs a role that operates apps. A widget JWT always shares for its own application.

## Request body

- object
  - `application_id` string: With an API key, the application the shared flow connects into (defaults to the key's own). A widget JWT may only omit it or send its own application id (403 otherwise).
  - `domain` string: Single domain the teammate will connect.
  - `domains` string[]: Several domains the teammate will connect.
  - `prefill` object: Arbitrary widget config to resume. Served back verbatim by `GET /share/{token}`, stamped with the normalized domain target(s).
  - `recipient_email` string, email: Optional. One plain address (no display name, no list) to email the link and the DNS records to, for example the person who runs the domain's DNS. The instructions cover `domain`, or the first of `domains`.
  - `note` string: Optional plain-text note quoted in the email (at most 280 characters; markup is shown as text, never interpreted). Ignored without `recipient_email`.

## Response `201`

Share link minted (and, with recipient_email, the email attempted)

- object
  - `link` string, uri, required: Absolute forwardable URL ending /share/<token>.
  - `job_id` string, required
  - `emailed_to` string, email: Present when the email was accepted for delivery; the normalized recipient address.
  - `email_error` 'not_sent': Present when recipient_email was given but the email could not be sent. The link is still valid.

## Other responses

- `400`: Error envelope: {code, title, details}.
- `401`: Error envelope: {code, title, details}.
- `403`: Error envelope: {code, title, details}.
- `404`: Error envelope: {code, title, details}.
- `429`: Share-by-email cap reached (`rate_limited`); no link was minted.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)