Sharing

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

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.

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

Request body

application_idstring

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).

domainstring

Single domain the teammate will connect.

domainsstring[]

Several domains the teammate will connect.

prefillobject

Arbitrary widget config to resume. Served back verbatim by GET /share/{token}, stamped with the normalized domain target(s).

recipient_emailstring 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.

notestring

Optional plain-text note quoted in the email (at most 280 characters; markup is shown as text, never interpreted). Ignored without recipient_email.

Response

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

linkstring uri required

Absolute forwardable URL ending /share/<token>.

job_idstring required
emailed_tostring 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.

Changes

No recorded changes to this operation across all 1 revision of this API.