# 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.

or

`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).

or

`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 <uri>

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 <uri> 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 <date-time>
    ISO 8601 timestamp when the registration lapses. Absent until the registrar reports one.
  - `redemptionEndsAt` string <date-time>
    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 <date-time> | 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 <date-time> 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 <date-time> | any
    ISO 8601 timestamp of the last DNS check. Null before the first one.
  - `lastVerifiedAt` string <date-time> | 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 <date-time>
        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 <uri> required
          - `retryAfter` string <date-time> 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 <uri>
      - `operationId` string
      - `requestId` string
      - `providerRequestId` string
      - `expiresAt` string <date-time>
        ISO 8601 timestamp after which this hint stops applying. Absent when it has no deadline.
      - `createdAt` string <date-time> required
        ISO 8601 timestamp when the record was added to inventory.
      - `updatedAt` string <date-time> 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 <date-time> required
  - `finishedAt` string <date-time>

## 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
```json
{
  "$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
```json
{
  "$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"
}
```