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 (HostState),
  "ownershipState": enum (OwnershipState),
  "requiredDnsUpdates": {
    object (DnsUpdates)
  },
  "issues": [
    {
      object (Status)
    }
  ],
  "certPreference": enum (Type),
  "cert": {
    object (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 (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 (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 (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 (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 (HostState)

Output only. The HostState of the domain name this CustomDomain refers to.
ownershipState

enum (OwnershipState)

Output only. The OwnershipState of the domain name this CustomDomain refers to.
requiredDnsUpdates

object (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 (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 (Type)

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 (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 (DnsRecordSet)
    }
  ],
  "desired": [
    {
      object (DnsRecordSet)
    }
  ],
  "checkTime": string
}
Fields
discovered[]

object (DnsRecordSet)

The set of DNS records Hosting discovered when inspecting a domain.
desired[]

object (DnsRecordSet)

The set of DNS records Hosting needs to serve secure content on the domain.
checkTime

string (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 (Status)
  },
  "records": [
    {
      object (DnsRecord)
    }
  ]
}
Fields
domainName

string

Output only. The domain name the record set pertains to.
checkError

object (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 (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 (Type),
  "rdata": string,
  "requiredAction": enum (Action)
}
Fields
domainName

string

Output only. The domain name the record pertains to, e.g. foo.bar.com..
type

enum (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 (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. A records determine which IPv4 addresses a domain name directs traffic towards.
CNAME A CNAME record, as defined in RFC 1035. 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. 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 AAAA records determine which IPv6 addresses a domain name directs traffic towards.
CAA

A CAA record, as defined in RFC 6844. 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 (Type),
  "state": enum (CertState),
  "verification": {
    object (CertVerification)
  },
  "issues": [
    {
      object (Status)
    }
  ],
  "createTime": string,
  "expireTime": string
}
Fields
type

enum (Type)

Output only. The certificate's type.
state

enum (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 (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 (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 (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 (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 (DnsUpdates)
  },
  "http": {
    object (HttpUpdate)
  }
}
Fields
dns

object (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 (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 (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 (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 (Status)

Output only. An error encountered during the last contents check. If null, the check completed successfully.

Methods

create

 Creates a CustomDomain.

delete

 Deletes the specified CustomDomain.

get

 Gets the specified CustomDomain.

list

 Lists each CustomDomain associated with the specified parent Hosting site.

patch

 Updates the specified CustomDomain.

undelete

 Undeletes the specified CustomDomain if it has been soft-deleted.