Management API: Hosted Subdomains

A hosted subdomain is a subdomain of your site, pointed at Fingerly with a CNAME, that serves the browser SDK when you can run no proxy. It needs no proxy key. Only admin management keys can manage them; a developer key answers 403.

Path parameter

organization_idstringrequired
Your organization, from Describe the key. A path naming any other organization answers 404.

List hosted subdomains

GET/api/v1/management/organizations/{organization_id}/hosted-domains Management key

Response

availableboolean
Whether hosted subdomains can be added on this deployment. Existing ones can always be listed and removed.
targetstring
What each subdomain's CNAME points at. Omitted when available is false.
domainsHostedDomain[]
Every hosted subdomain.
8 child fields
- idstring
  The hosted subdomain's ID.
- hostnamestring
  The subdomain, such as k7.shop.example.
- pathstring
  Where the browser SDK posts on it, such as /q3v8wz1p.
- statusstring
  pending while the record does not resolve or the certificate is being issued, active once it is served, or failed.
- problemstring
  Why the certificate is not issued yet, or why it failed. Omitted when there is nothing to report.
- checked_atstring
  When its DNS and certificate were last checked.
- activated_atstring
  When it became active. Omitted until then.
- created_atstring
  When it was added.

Add a hosted subdomain

POST/api/v1/management/organizations/{organization_id}/hosted-domains Management key

Body

hostnamestringrequired
A subdomain of your site, such as k7.shop.example, never the domain itself. A label a content blocker would match, such as fp, metrics or tracking, is refused.
pathstring
Where the browser SDK will post on it. Omit it for a random one, which is what we recommend. It follows the rules of a proxy path.

Answers 201 with the hosted subdomain, pending until its CNAME to target resolves and its certificate is issued. Create the record, then point the browser SDK's endpoints at https://<hostname><path>.

Pending subdomains are checked every 30 seconds, so there is no need to poll. Read the list, or check one at once, to follow it.

Check a hosted subdomain now

POST/api/v1/management/organizations/{organization_id}/hosted-domains/{hosted_domain_id}/check Management key

Checks the subdomain's DNS and certificate at once, rather than at the next scheduled check, and answers with the hosted subdomain as it is now. This is Check now in the dashboard.

Remove a hosted subdomain

DELETE/api/v1/management/organizations/{organization_id}/hosted-domains/{hosted_domain_id} Management key

Stops serving the subdomain at once, drops its certificate, and answers 204. Delete the CNAME at your DNS host afterwards. There is no undo: adding the name again starts over with a new certificate.

Errors

Status	Code	When
`404`	`hosted_domain_not_found`	No such hosted subdomain in your organization.
`409`	`hosted_domains_unavailable`	Hosted subdomains cannot be added on this deployment. `available` says so in advance.
`409`	`hosted_domain_taken`	The name is already a hosted subdomain, of your organization or another.
`422`	`hosted_domain_rejected`	The name is not usable: not a subdomain, not a valid hostname, one of Fingerly's own, or a label content blockers match. `error.message` says which.
`422`	`proxy_path_rejected`	The `path` is not valid, or contains a word content blockers match. `error.message` names it.