Verify a domain - Spacefast Docs

Verify a domain

Checks public DNS for proof of control over the hostname, updates the verification state, and resyncs the Space serving it. Returns the domain and the runtime operation. Limited to 6 checks per hour per domain and 120 per hour per team.

POST `/v1/domains/{domainId}/verify`

Authorization

Authorization Bearer token · header required

Authorization: Bearer <key> with the Space key (sfc_ prefix) of an unclaimed Space. The same key is the fragment of the claim URL and the token in the Space's /_/<key> sign-in URL.

Authorization Bearer token · header required

Authorization: Bearer <token> with an API key (sfa_ prefix), an OAuth access token, a session token, or a Space machine credential (sfm_ prefix).

Authorization OAuth2 access token · header required

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

Scopes: `domains:write`

Path parameters

domainId string required

Responses

200 Response for status 200

$schema string

Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

data object required

id string required Domain inventory record ID (dom_ prefix).
name string required Canonical hostname in lowercase ASCII A-labels, punycoded per IDNA2008, with no trailing dot and no wildcard label.
unicodeName string Unicode U-label form of name. Absent when the two are identical.
kind string required apex when name equals derivedGroup, hostname otherwise. Server-derived; never accepted as input. Allowed: hostname, apex
wildcardEnabled boolean required Whether wildcard hostnames may be derived under this record.
spaceId string | any required Space this hostname serves (spc_ prefix). Null while the record is inventory only. One Space per hostname; a Space may hold many.

`primary` boolean required

Whether the Space points its liveUrl at this hostname.

`redirect` object

Whole-host redirect this hostname answers with instead of serving. Absent when it serves.

to object required Where the hostname redirects: an absolute URL, or a Space with an optional path.
- url string required Absolute URL the hostname redirects to.
- spaceId string required Space the hostname redirects to (spc_ prefix).
- path string Path to land on at the target Space. Omit to redirect to its root.
- status string required Allowed: 301, 302, 307, 308
derivedGroup string required Registrable domain of name under the Public Suffix List. Server-computed; never accepted as input.
registrar object Registration state. Present only on apex records.
- provider string Registrar the registration lives with, for example wpcom. Absent while mode is external.
- status string Where the registration sits in its lifecycle. expiring is derived from expiresAt rather than stored, and expired keeps serving intact until redemptionEndsAt passes. Allowed: active, pending_purchase, pending_transfer_in, expiring, expired, locked
- expiresAt string ISO 8601 timestamp when the registration lapses. Absent until the registrar reports one.
- redemptionEndsAt string ISO 8601 timestamp when the registrar closes the redemption window opened by expiry. Serving stays intact until then.
- autoRenew boolean Whether the registrar renews the domain before it expires. Absent when no registration record exists yet.
- transferLock boolean Whether the registrar refuses outbound transfers. Absent when no registration record exists yet.
dns object DNS hosting state. Present only on records that own their zone cut: the apex, or a hostname whose own nameservers are observed in public DNS.
- managementKind string Who actually holds the zone: unmanaged_external with no credential or delegation, connected_provider through a linked provider account, registrar_dns on the Spacefast registrar, stattic_nameservers once delegation lands on Spacefast nameservers. Allowed: unmanaged_external, connected_provider, registrar_dns, stattic_nameservers
- dnsMode string authoritative when Spacefast answers for the zone, adapter when records are written to or observed on another DNS host. Derived from managementKind. Allowed: authoritative, adapter
provider string DNS host that answers for the zone, for example route53 or cloudflare. Absent on an external zone with no provider connection attached.
assignedNameservers string[] Nameservers the registrar delegation has to point at. Present only while mode is stattic.
observedNameservers string[] Nameservers seen in public DNS at the last poll, in either mode. Absent until a poll observes any.
snapshot object Freshness of the cached record read from the connected provider. Present only once a provider zone is attached.
- freshness string required Allowed: fresh, stale, refresh_running, refresh_failed, never_fetched
lastFetchedAt string | any required

`version` string | any required

Snapshot version string the provider returned. Null when it returns none.

lastOperation object Newest DNS operation on this zone. Absent until one runs.
- id string required
- kind string required
- status string required Allowed: queued, running, observing, succeeded, failed, canceled
- updatedAt string required
verification object required Proof-of-DNS-control state for this hostname.
- status string required Current proof of DNS control: not_required while the domain serves no Space, pending once it selects one, verified on a positive DNS signal, failed after a check stops proving control. A failed status never tears down serving on its own. Allowed: not_required, pending, verified, failed
requiredRecords object[] Records the caller still has to create to prove control and route traffic. Absent once the hostname serves, and while the domain serves no Space.
- type string required Allowed: A, AAAA, CNAME, TXT, ALIAS
- name string required Record name, relative to the zone.
- value string required Exact value to set on the record.
- ttl integer min -9007199254740991 · max 9007199254740991
- purpose string required Why the record is needed: verification proves ownership, routing sends traffic to the Space, ssl allows certificate issuance. Allowed: verification, routing, ssl
- lastCheckedAt string | any ISO 8601 timestamp of the last DNS check. Null before the first one.
- lastVerifiedAt string | any ISO 8601 timestamp when this domain last proved DNS control. Null if it never has.
- diagnostics object[] Stable-coded observations about verification, delegation, and registration state. Absent when there are none.
  - code string required
  - severity string required Allowed: info, warning, error
  - message string required What happened, in a sentence a person can act on.
  - path string | any File or artifact path the diagnostic refers to, with a line number when known, for example /_headers:12. Absent when it applies to the whole resource.
- provider string | any Upstream system that raised the diagnostic. Absent when Spacefast raised it.
- details object | any Machine-readable context keyed by the diagnostic code.
- fix string | any What to change to clear the diagnostic. Absent when there is no known fix.
- retryable boolean | any True when repeating the same operation unchanged can clear the diagnostic.
- hints object[] Recovery guidance derived from the newest failed DNS operation. Absent when the last operation did not fail.
  - id string required
  - code string required
  - severity string required Allowed: info, warning, error
  - painLevel string required Allowed: info, needs_attention, blocked, broken, dangerous
  - subjectFacet string required Allowed: dns_zone, registrar, hosting_binding, email, forwarding, provider_connection
  - subjectRef object required
    - domainId string required
    - zoneId string
    - bindingId string
    - connectionId string
  - owner string required Who has to move next. stattic is Spacefast itself, waiting means nobody acts until a timer or an external system settles. Allowed: stattic, user, registrar, provider, support, waiting
  - status string required Allowed: active, waiting, running, resolved, dismissed
  - summary string required
  - description string required
  - impact string required
  - evidence object[] required
    - label string required
    - value string required
    - observedAt string matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:.[\d]+)?(?:Z))$
    - source string required Allowed: provider_api, public_dns, registrar, stattic_db, operation, user_input
  - suggestions object[] required
    - label string required
    - description string required
    - action object required
      - One of:
        
        type string required
        
        actionId string required
        
        records object[] required
        
        type string required Allowed: A, AAAA, CNAME, TXT, ALIAS
        
        name string required Record name, relative to the zone.
        
        value string required Exact value to set on the record.
        
        ttl integer min -9007199254740991 · max 9007199254740991
        
        target string required
        
        connectionId string required
        
        url string required
        
        retryAfter string required matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:.[\d]+)?(?:Z))$
    - primary boolean
    - destructive boolean
    - docsUrl string
    - operationId string
    - requestId string
    - providerRequestId string
    - expiresAt string ISO 8601 timestamp after which this hint stops applying. Absent when it has no deadline.
    - createdAt string required ISO 8601 timestamp when the record was added to inventory.
    - updatedAt string required ISO 8601 timestamp when the record last changed.
operation object | any required Background operation still running after this call. Null when all work finished before the response.
- id string required
- kind string required
- status string required Allowed: queued, running, succeeded, failed, canceled
- resources object[] required
  - type string required
  - id string required
- progress object
  - total integer required min 0 · max 9007199254740991
  - completed integer required min 0 · max 9007199254740991
  - failed integer required min 0 · max 9007199254740991
- diagnostics object[]
  - code string required
  - severity string required Allowed: info, warning, error
  - message string required
  - path string | any
  - provider string | any
  - details object | any
  - fix string | any
  - retryable boolean | any
- createdAt string required
- finishedAt string

Try it

Server

Base URL https://api.spacefast.com

Custom base URL Overrides the selected server when set.

Authorization

Bearer token Remember on this device Include my values in samples

Parameters

domainId path*

Send

Request

cURL

curl -X POST "https://api.spacefast.com/v1/domains/string/verify" \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript

const response = await fetch("https://api.spacefast.com/v1/domains/string/verify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

Python

import requests

response = requests.post(
    "https://api.spacefast.com/v1/domains/string/verify",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

200 default

{
  "$schema": "http://example.com",
  "data": {
    "id": "string",
    "name": "string",
    "unicodeName": "string",
    "kind": "hostname",
    "wildcardEnabled": true,
    "spaceId": "string",
    "primary": true,
    "redirect": {
      "to": {
        "url": "http://example.com"
      },
      "status": 301
    },
    "derivedGroup": "string",
    "registrar": {
      "provider": "string",
      "status": "active",
      "expiresAt": "2019-08-24T14:15:22Z",
      "redemptionEndsAt": "2019-08-24T14:15:22Z",
      "autoRenew": true,
      "transferLock": true
    },
    "dns": {
      "managementKind": "unmanaged_external",
      "dnsMode": "authoritative",
      "provider": "string",
      "assignedNameservers": [
        "string"
      ],
      "observedNameservers": [
        "string"
      ],
      "snapshot": {
        "freshness": "fresh",
        "lastFetchedAt": "2019-08-24T14:15:22Z",
        "version": "string"
      },
      "lastOperation": {
        "id": "string",
        "kind": "string",
        "status": "queued",
        "updatedAt": "2019-08-24T14:15:22Z"
      }
    },
    "verification": {
      "status": "not_required",
      "requiredRecords": [
        {
          "type": "A",
          "name": "string",
          "value": "string",
          "ttl": -9007199254740991,
          "purpose": "verification"
        }
      ],
      "lastCheckedAt": "2019-08-24T14:15:22Z",
      "lastVerifiedAt": "2019-08-24T14:15:22Z",
      "diagnostics": [
        {
          "code": "string",
          "severity": "info",
          "message": "string",
          "path": "string",
          "provider": "infra",
          "details": {
            "property1": null,
            "property2": null
          },
          "fix": "string",
          "retryable": true
        }
      ]
    },
    "hints": [
      {
        "id": "string",
        "code": "string",
        "severity": "info",
        "painLevel": "info",
        "subjectFacet": "dns_zone",
        "subjectRef": {
          "domainId": "string",
          "zoneId": "string",
          "bindingId": "string",
          "connectionId": "string"
        },
        "owner": "stattic",
        "status": "active",
        "summary": "string",
        "description": "string",
        "impact": "string",
        "evidence": [
          {
            "label": "string",
            "value": "string",
            "observedAt": "2019-08-24T14:15:22Z",
            "source": "provider_api"
          }
        ],
        "suggestions": [
          {
            "label": "string",
            "description": "string",
            "action": {
              "type": "open_pending_action",
              "actionId": "string"
            },
            "primary": true,
            "destructive": true
          }
        ],
        "docsUrl": "http://example.com",
        "operationId": "string",
        "requestId": "string",
        "providerRequestId": "string",
        "expiresAt": "2019-08-24T14:15:22Z"
      }
    ],
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  },
  "operation": {
    "id": "string",
    "kind": "string",
    "status": "queued",
    "resources": [
      {
        "type": "string",
        "id": "string"
      }
    ],
    "progress": {
      "total": 9007199254740991,
      "completed": 9007199254740991,
      "failed": 9007199254740991
    },
    "diagnostics": [
      {
        "code": "string",
        "severity": "info",
        "message": "string",
        "path": "string",
        "provider": "infra",
        "details": {
          "property1": null,
          "property2": null
        },
        "fix": "string",
        "retryable": true
      }
    ],
    "createdAt": "2019-08-24T14:15:22Z",
    "finishedAt": "2019-08-24T14:15:22Z"
  }
}

Error Response

{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}

Verify a domain

POST /v1/domains/{domainId}/verify

Authorization

Scopes: domains:write

Path parameters

Responses

200 Response for status 200

primary boolean required

redirect object

version string | any required

Try it

Server

Authorization

Parameters

Send

Request

cURL

JavaScript

Python

Response

200 default

Error Response

POST `/v1/domains/{domainId}/verify`

Scopes: `domains:write`

`primary` boolean required

`redirect` object

`version` string | any required