---
title: "Share a custom domain"
method: POST
path: "/customdomains/{domainName}/share"
tags: ["customdomains"]
---

# Share a custom domain

`POST /customdomains/{domainName}/share`

## Request

- Base URL: `https://api.blaxel.ai/v0`
- URL: `https://api.blaxel.ai/v0/customdomains/{domainName}/share`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/oauth/authorize`
    - Client credentials
    - Token URL: `/oauth/token` scopes: `customdomains:update`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/blaxel/apis/blaxel-control-plane/docs/customdomains/:domainName/share/post.ts> (a function with typed inputs; its response is checked against the schema)

Shares a verified custom domain with another workspace of the same account by copying the domain record; the ACM certificate and CloudFront tenant stay with the owner and are reused (not re-provisioned). Use targetWorkspace "account" to make the domain usable by every workspace of the account. Cross-account sharing is not supported.

## Path parameters

- `domainName` string, required

## Request body

- object
  - `targetWorkspace` string, required: Name of the workspace to share the domain with, or "account" to share with every workspace of the account.

## Response `200`

successful operation

- CustomDomain: Custom domain for preview deployments The custom domain represents a base domain (e.g., example.com) that will be used to serve preview deployments. Each preview will be accessible at a subdomain: <preview-id>.preview.<base-domain> (e.g., abc123.preview.example.com)
  - `metadata` CustomDomainMetadata, required: Owner fields for Persistence
    - `createdAt` string: The date and time when the resource was created
    - `updatedAt` string: The date and time when the resource was updated
    - `createdBy` string: The user or service account who created the resource
    - `updatedBy` string: The user or service account who updated the resource
    - `displayName` string: Display name for the custom domain
    - `labels` MetadataLabels: Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy.
    - `name` string: Domain name (e.g., "example.com")
    - `sharedFromWorkspace` string: If this custom domain is shared from another workspace of the same account, this field contains the name of the source (owning) workspace. Empty for owned domains.
    - `workspace` string: Workspace name
  - `spec` CustomDomainSpec, required: Custom domain specification
    - `cnameRecords` string: CNAME target for the domain
    - `domainType` 'previews' | 'applications': Type of custom domain (previews or applications)
    - `fallbackPreviewId` string: Preview ID to route to when a preview lookup fails on this custom domain
    - `lastVerifiedAt` string: Last verification attempt timestamp
    - `region` string: Region that the custom domain is associated with
    - `status` 'pending' | 'verified' | 'failed': Current status of the domain (pending, verified, failed)
    - `subjectAlternativeNames` object[]: Subject Alternative Names (SANs) for the ACM certificate. Only applicable for application domains.
    - `txtRecords` object: Map of TXT record names to values for domain verification
    - `verificationError` string: Error message if verification failed

## Other responses

- `400`: invalid request
- `404`: custom domain not found
- `409`: custom domain conflict in target workspace

---

[API](https://skmtc.dev/blaxel/apis/blaxel-control-plane.md) - [All operations](https://skmtc.dev/blaxel/apis/blaxel-control-plane/llms.txt) - [OpenAPI document](https://skmtc.dev/blaxel/apis/blaxel-control-plane/revisions/dfa264bc72ee?raw)