# REST Resource: projects.sites.customDomains

## Resource: CustomDomain

A `CustomDomain` is an entity that links a domain name to a Firebase Hosting site. Add a `CustomDomain` to your site to allow Hosting to serve the site's content in response to requests against your domain name.

| JSON representation |
|---|
| ``` { "name": string, "annotations": { string: string, ... }, "createTime": string, "updateTime": string, "deleteTime": string, "expireTime": string, "etag": string, "hostState": enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#HostState`), "ownershipState": enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#OwnershipState`), "requiredDnsUpdates": { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsUpdates`) }, "issues": [ { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/Status`) } ], "certPreference": enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Type_1`), "cert": { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Certificate`) }, "redirectTarget": string, "reconciling": boolean, "labels": { string: string, ... } } ``` |

| Fields ||
|---|---|
| `name` | `string` Output only. The fully-qualified name of the `CustomDomain`. |
| `annotations` | `map (key: string, value: string)` Annotations you can add to leave both human- and machine-readable metadata about your `CustomDomain`. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |
| `createTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` Output only. The custom domain's create time. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |
| `updateTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` Output only. The last time the `CustomDomain` was updated. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |
| `deleteTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` Output only. The time the `CustomDomain` was deleted; null for custom domains that haven't been deleted. Deleted custom domains persist for approximately 30 days, after which time Hosting removes them completely. To restore a deleted custom domain, make an `customDomains.undelete` request. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |
| `expireTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` Output only. The minimum time before a soft-deleted `CustomDomain` is completely removed from Hosting; null for custom domains that haven't been deleted. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |
| `etag` | `string` Output only. A string that represents the current state of the `CustomDomain` and allows you to confirm its initial state in requests that would modify it. Use the tag to ensure consistency when making `customDomains.patch`, `customDomains.delete`, and `customDomains.undelete` requests. |
| `hostState` | ``enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#HostState`)`` Output only. The `HostState` of the domain name this `CustomDomain` refers to. |
| `ownershipState` | ``enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#OwnershipState`)`` Output only. The `OwnershipState` of the domain name this `CustomDomain` refers to. |
| `requiredDnsUpdates` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsUpdates`)`` Output only. A set of updates you should make to the domain name's DNS records to let Hosting serve secure content on its behalf. |
| `issues[]` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/Status`)`` Output only. A set of errors Hosting systems encountered when trying to establish Hosting's ability to serve secure content for your domain name. Resolve these issues to ensure your `CustomDomain` behaves properly. |
| `certPreference` | ``enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Type_1`)`` A field that lets you specify which SSL certificate type Hosting creates for your domain name. Spark plan custom domains only have access to the `GROUPED` cert type, while Blaze plan domains can select any option. |
| `cert` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Certificate`)`` Output only. The SSL certificate Hosting has for this custom domain's domain name. For new custom domains, this often represents Hosting's intent to create a certificate, rather than an actual cert. Check the `state` field for more. |
| `redirectTarget` | `string` A domain name that this `CustomDomain` should direct traffic towards. If specified, Hosting will respond to requests against this custom domain with an HTTP 301 code, and route traffic to the specified `redirectTarget` instead. |
| `reconciling` | `boolean` Output only. A field that, if true, indicates that Hosting's systems are attmepting to make the custom domain's state match your preferred state. This is most frequently `true` when initially provisioning a `CustomDomain` after a `customDomains.create` request or when creating a new SSL certificate to match an updated `certPreference` after an `customDomains.patch` request. |
| `labels` | `map (key: string, value: string)` Labels used for extra metadata and/or filtering. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |

## HostState

The host state of your domain name. Host state is determined by checking each IP address associated with your domain name to see if it's serving Hosting content.

| Enums ||
|---|---|
| `HOST_STATE_UNSPECIFIED` | Your custom domain's host state is unspecified. The message is invalid if this is unspecified. |
| `HOST_UNHOSTED` | Your custom domain's domain name isn't associated with any IP addresses. |
| `HOST_UNREACHABLE` | Your custom domain's domain name can't be reached. Hosting services' DNS queries to find your domain name's IP addresses resulted in errors. See your `CustomDomain` object's `issues` field for more details. |
| `HOST_MISMATCH` | Your custom domain's domain name has IP addresses that don't ultimately resolve to Hosting. |
| `HOST_CONFLICT` | Your custom domain's domain name has IP addresses that resolve to both Hosting and other services. To ensure consistent results, remove `A` and `AAAA` records related to non-Hosting services. |
| `HOST_ACTIVE` | All requests against your custom domain's domain name are served by Hosting. If the custom domain's `OwnershipState` is also `ACTIVE`, Hosting serves your Hosting site's content on the domain name. |

## OwnershipState

The ownership state of your domain. A domain can be owned by at most one Firebase Hosting Site. Ownership can be determined in two ways:

    * TXT records: A TXT record on the domain in the form
    `hosting-site=[siteId]`.
    * CNAME records: A CNAME record that points to a Hosting site's default
    domain.

If your `CustomDomain` is in an `OwnershipState` other than `OWNERSHIP_ACTIVE` for more than 30 days and it hasn't been updated in at least 30 days, Hosting's ownership systems delete the `CustomDomain`. To restore a deleted `CustomDomain`, make an `customDomains.undelete` request.

| Enums ||
|---|---|
| `OWNERSHIP_STATE_UNSPECIFIED` | Your custom domain's ownership state is unspecified. This should never happen. |
| `OWNERSHIP_MISSING` | Your custom domain's domain name has no Hosting-related ownership records; no Firebase project has permission to act on the domain name's behalf. |
| `OWNERSHIP_UNREACHABLE` | Your custom domain's domain name can't be reached. Hosting services' DNS queries to find your domain name's ownership records resulted in errors. See your `CustomDomain` object's `issues` field for more details. |
| `OWNERSHIP_MISMATCH` | Your custom domain's domain name is owned by another Firebase project. Remove the conflicting `TXT` records and replace them with project-specific records for your current Firebase project. |
| `OWNERSHIP_CONFLICT` | Your custom domain's domain name has conflicting `TXT` records that indicate ownership by both your current Firebase project and another project. Remove the other project's ownership records to grant the current project ownership. |
| `OWNERSHIP_PENDING` | Your custom domain's DNS records are configured correctly. Hosting will transfer ownership of your domain to this `CustomDomain` within 24 hours. |
| `OWNERSHIP_ACTIVE` | Your custom domain's domain name has `TXT` records that grant its project permission to act on its behalf. |

## DnsUpdates

A set of DNS record updates that you should make to allow Hosting to serve secure content in response to requests against your domain name. These updates present the current state of your domain name's DNS records when Hosting last queried them, and the desired set of records that Hosting needs to see before your custom domain can be fully active.

| JSON representation |
|---|
| ``` { "discovered": [ { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsRecordSet`) } ], "desired": [ { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsRecordSet`) } ], "checkTime": string } ``` |

| Fields ||
|---|---|
| `discovered[]` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsRecordSet`)`` The set of DNS records Hosting discovered when inspecting a domain. |
| `desired[]` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsRecordSet`)`` The set of DNS records Hosting needs to serve secure content on the domain. |
| `checkTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` The last time Hosting checked your custom domain's DNS records. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |

## DnsRecordSet

A set of DNS records relevant to the setup and maintenance of a custom domain in Firebase Hosting.

| JSON representation |
|---|
| ``` { "domainName": string, "checkError": { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/Status`) }, "records": [ { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsRecord`) } ] } ``` |

| Fields ||
|---|---|
| `domainName` | `string` Output only. The domain name the record set pertains to. |
| `checkError` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/Status`)`` Output only. An error Hosting services encountered when querying your domain name's DNS records. Note: Hosting ignores `NXDOMAIN` errors, as those generally just mean that a domain name hasn't been set up yet. |
| `records[]` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsRecord`)`` Output only. Records on the domain. |

## DnsRecord

DNS records are resource records that define how systems and services should behave when handling requests for a domain name. For example, when you add `A` records to your domain name's DNS records, you're informing other systems (such as your users' web browsers) to contact those IPv4 addresses to retrieve resources relevant to your domain name (such as your Hosting site files).

| JSON representation |
|---|
| ``` { "domainName": string, "type": enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Type`), "rdata": string, "requiredAction": enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Action`) } ``` |

| Fields ||
|---|---|
| `domainName` | `string` Output only. The domain name the record pertains to, e.g. `foo.bar.com.`. |
| `type` | ``enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Type`)`` Output only. The record's type, which determines what data the record contains. |
| `rdata` | `string` Output only. The data of the record. The meaning of the value depends on record type: - A and AAAA: IP addresses for the domain name. - CNAME: Another domain to check for records. - TXT: Arbitrary text strings associated with the domain name. Hosting uses TXT records to determine which Firebase projects have permission to act on the domain name's behalf. - CAA: The record's flags, tag, and value, e.g. `0 issue "pki.goog"`. |
| `requiredAction` | ``enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Action`)`` Output only. An enum that indicates the a required action for this record. |

## Type

The type of the DNS record, including `A`, `TXT`, `AAAA`, and `CAA`.

| Enums ||
|---|---|
| `TYPE_UNSPECIFIED` | The record's type is unspecified. The message is invalid if this is unspecified. |
| `A` | An `A` record, as defined in [RFC 1035](https://tools.ietf.org/html/rfc1035). A records determine which IPv4 addresses a domain name directs traffic towards. |
| `CNAME` | A `CNAME` record, as defined in [RFC 1035](https://tools.ietf.org/html/rfc1035). `CNAME` or Canonical Name records map a domain name to a different, canonical domain name. If a `CNAME` record is present, it should be the only record on the domain name. |
| `TXT` | A `TXT` record, as defined in [RFC 1035](https://tools.ietf.org/html/rfc1035). `TXT` records hold arbitrary text data on a domain name. Hosting uses `TXT` records to establish which Firebase Project has permission to act on a domain name. |
| `AAAA` | An AAAA record, as defined in [RFC 3596](https://tools.ietf.org/html/rfc3596) AAAA records determine which IPv6 addresses a domain name directs traffic towards. |
| `CAA` | A CAA record, as defined in [RFC 6844](https://tools.ietf.org/html/rfc6844). CAA, or Certificate Authority Authorization, records determine which Certificate Authorities (SSL certificate minting organizations) are authorized to mint a certificate for the domain name. Firebase Hosting uses `pki.goog` as its primary CA. CAA records cascade. A CAA record on `foo.com` also applies to `bar.foo.com` unless `bar.foo.com` has its own set of CAA records. CAA records are optional. If a domain name and its parents have no CAA records, all CAs are authorized to mint certificates on its behalf. In general, Hosting only asks you to modify CAA records when doing so is required to unblock SSL cert creation. |

## Action

Action is a type of action you should take on this DNS record to configure your domain for use with Firebase Hosting.

| Enums ||
|---|---|
| `NONE` | No action necessary. |
| `ADD` | Add this record to your DNS records. |
| `REMOVE` | Remove this record from your DNS records. |

## Type

The certificate's type. Determines how Hosting systems handle create and maintain the certificate.

| Enums ||
|---|---|
| `TYPE_UNSPECIFIED` | The certificate's type is unspecified. The message is invalid if this is unspecified. |
| `TEMPORARY` | A short-lived certificate type that covers a domain name temporarily, while Hosting creates a more permanent certificate. |
| `GROUPED` | The standard certificate for Spark plan custom domains. |
| `PROJECT_GROUPED` | Blaze plan only. A certificate that covers from 1 to 100 domain names with custom domains on the same Firebase project. |
| `DEDICATED` | Blaze plan only. A certificate that covers a single domain name. |

## Certificate

An SSL certificate used to provide end-to-end encryption for requests against your domain name. A `Certificate` can be an actual SSL certificate or, for newly-created custom domains, Hosting's intent to create one.

| JSON representation |
|---|
| ``` { "type": enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Type_1`), "state": enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#CertState`), "verification": { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#CertVerification`) }, "issues": [ { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/Status`) } ], "createTime": string, "expireTime": string } ``` |

| Fields ||
|---|---|
| `type` | ``enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#Type_1`)`` Output only. The certificate's type. |
| `state` | ``enum (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#CertState`)`` Output only. The state of the certificate. Only the `CERT_ACTIVE` and `CERT_EXPIRING_SOON` states provide SSL coverage for a domain name. If the state is `PROPAGATING` and Hosting had an active cert for the domain name before, that formerly-active cert provides SSL coverage for the domain name until the current cert propagates. |
| `verification` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#CertVerification`)`` Output only. A set of ACME challenges you can add to your DNS records or existing, non-Hosting hosting provider to allow Hosting to create an SSL certificate for your domain name before you point traffic toward hosting. You can use thse challenges as part of a zero downtime transition from your old provider to Hosting. |
| `issues[]` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/Status`)`` Output only. A set of errors Hosting encountered when attempting to create a cert for your domain name. Resolve these issues to ensure Hosting is able to provide secure communication with your site's visitors. |
| `createTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` Output only. The certificate's creation time. For `TEMPORARY` certs this is the time Hosting first generated challenges for your domain name. For all other cert types, it's the time the actual cert was created. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |
| `expireTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` Output only. The certificate's expiration time. After this time, the cert can no longer be used to provide secure communication between Hosting and your site's visitors. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |

## CertState

The state of the SSL certificate Hosting has for your domain name. This can represent either the state of the actual certificate or, for new custom domains, Hosting's attempt to create a certificate.

| Enums ||
|---|---|
| `CERT_STATE_UNSPECIFIED` | The certificate's state is unspecified. The message is invalid if this is unspecified. |
| `CERT_PREPARING` | The initial state of every certificate, represents Hosting's intent to create a certificate, before requests to a Certificate Authority are made. |
| `CERT_VALIDATING` | Hosting is validating whether a domain name's DNS records are in a state that allow certificate creation on its behalf. |
| `CERT_PROPAGATING` | The certificate was recently created, and needs time to propagate in Hosting's CDN. |
| `CERT_ACTIVE` | The certificate is active, providing secure connections for the domain names it represents. |
| `CERT_EXPIRING_SOON` | The certificate is expiring, all domain names on it will be given new certificates. |
| `CERT_EXPIRED` | The certificate has expired. Hosting can no longer serve secure content on your domain name. |

## CertVerification

A set of ACME challenges you can use to allow Hosting to create an SSL certificate for your domain name before directing traffic to Hosting servers. Use either the DNS or HTTP challenge; it's not necessary to provide both.

| JSON representation |
|---|
| ``` { "dns": { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsUpdates`) }, "http": { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#HttpUpdate`) } } ``` |

| Fields ||
|---|---|
| `dns` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#DnsUpdates`)`` Output only. A `TXT` record to add to your DNS records that confirms your intent to let Hosting create an SSL cert for your domain name. |
| `http` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains#HttpUpdate`)`` Output only. A file to add to your existing, non-Hosting hosting service that confirms your intent to let Hosting create an SSL cert for your domain name. |

## HttpUpdate

A file you can add to your existing, non-Hosting hosting service that confirms your intent to allow Hosting's Certificate Authorities to create an SSL certificate for your domain.

| JSON representation |
|---|
| ``` { "path": string, "desired": string, "discovered": string, "lastCheckTime": string, "checkError": { object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/Status`) } } ``` |

| Fields ||
|---|---|
| `path` | `string` Output only. The path to the file. |
| `desired` | `string` Output only. A text string to serve at the path. |
| `discovered` | `string` Output only. Whether Hosting was able to find the required file contents on the specified path during its last check. |
| `lastCheckTime` | ``string (`https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp` format)`` Output only. The last time Hosting systems checked for the file contents. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: `"2014-10-02T15:01:23Z"` and `"2014-10-02T15:01:23.045123456Z"`. |
| `checkError` | ``object (`https://firebase.google.com/docs/reference/hosting/rest/v1beta1/Status`)`` Output only. An error encountered during the last contents check. If null, the check completed successfully. |

| ## Methods ||
|---|---|
| ### `https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains/create` | Creates a `CustomDomain`. |
| ### `https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains/delete` | Deletes the specified `CustomDomain`. |
| ### `https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains/get` | Gets the specified `CustomDomain`. |
| ### `https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains/list` | Lists each `CustomDomain` associated with the specified parent Hosting site. |
| ### `https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains/patch` | Updates the specified `CustomDomain`. |
| ### `https://firebase.google.com/docs/reference/hosting/rest/v1beta1/projects.sites.customDomains/undelete` | Undeletes the specified `CustomDomain` if it has been soft-deleted. |