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

Server URLloading...

POST

/sharing/connect

Send

Authorization

Body

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, so such a token must name a domain or domains (400 otherwise). 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.

Whose end user the recipient is. The recipient's widget token names the end user the sharer is, recorded when the link is made and never worked out from the domain when it is opened. A widget token shares as its own end_user_ref (none when it names none). An API key or an app-scoped token shares as the end_user_ref of the application's connection for the one domain the link names, and as no end user when there is no connection for it yet, the connection names none, or the link names several domains or none. A connection that names an end user answers only a widget token that names the same one, so this is what lets the recipient reach the connection the link was made for; another end user who shares this one's domain gets a token that names itself and is still refused on it. A prefill key the control plane records this in is dropped from the caller's prefill and never read back.

What a widget token may share. Only a domain whose connection in the application its own token owns, by the rule every managed DNS route applies: a connection that names the token's end_user_ref; one that names no end user when the token is bound to that domain; and, for a token that names no end user and is bound to no domain, the connection of the domain it is asked about, since it counts only that connection as its own (a token with an end_user_ref and no bound domain owns none that names no end user). Any other shared domain is refused with 403 token_wrong_end_user and no link is made. A domain with no connection yet can be shared.

What the recipient owns and reaches. One rule: the recipient owns exactly what the sharer owned, and may touch only the shared domains. It owns the sharer's end user and the domains the sharer's own binding made its own, recorded when the link is made, and never the shared domains it is bound to: a link made by a token that names no end user and is bound to none owns each connection by itself, so a zone that links several of the shared domains is not its own. It reaches the shared domains, intersected with the sharer's binding when the sharer was bound: an end user that is bound to no domain, sharing one of its domains, gives a token that reaches that domain and none of its others. A link made by the platform's API key or an app-scoped token owns by the end user of the connection it names (or none) and reaches the shared domains.

Response Body

curl -X POST "https://example.com/sharing/connect" \  -H "Content-Type: application/json" \  -d '{}'

{  "link": "http://example.com",  "job_id": "string",  "emailed_to": "[email protected]",  "email_error": "not_sent"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}

{  "code": "string",  "title": "string",  "details": "string"}