---
title: "Confirm authorisation to assess"
method: POST
path: "/v1/domains/{domainId}/authorisation"
tags: ["Domains"]
---

# Confirm authorisation to assess

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

## Request

- Base URL: `https://api.ironfang.com/security`
- URL: `https://api.ironfang.com/security/v1/domains/{domainId}/authorisation`
- Auth: HTTP bearer

Records that the acting user confirmed the current scan policy's statement for this verified domain. The record is immutable and names the policy and statement versions. A new policy version requires a new confirmation.

## Request body

- AuthoriseRequest
  - `confirm` true, required
  - `policy_version` string, required
  - `statement_version` string, required

## Response `201`

The domain with its authorisation.

- Domain
  - `authorised` boolean, required
  - `can_scan` boolean, required
  - `created_at` string, date-time, required
  - `display_name` string, required
  - `id` string, uuid, required
  - `latest_scan` ScanSummary
    - `changes` ScanChanges
      - `fixed` integer, required
      - `new` integer, required
      - `reopened` integer, required
    - `counts` ScanCounts, required
      - `confirmed` integer, required: Findings with confirmed or high confidence.
      - `critical` integer, required
      - `errors` integer, required: Checks that could not complete.
      - `high` integer, required
      - `info` integer, required
      - `low` integer, required
      - `medium` integer, required
      - `passed` integer, required: Checks that observed a control working.
      - `unverified` integer, required: Findings with medium or low confidence.
    - `domain` string, required
    - `domain_id` string, uuid, required
    - `duration_ms` integer
    - `failure_class` 'asset' | 'ironfang': For a failed scan, whose problem it was — the domain did not answer, or Ironfang could not run it.
    - `finished_at` string, date-time
    - `id` string, uuid, required
    - `kind` 'full' | 'recheck' | 'certificate', required: `certificate` is monitoring looking at one host's certificate again before warning that it is about to expire.
    - `progress` object, required
      - `completed` integer, required
      - `total` integer, required
    - `recheck_finding_id` string, uuid
    - `requested_at` string, date-time, required
    - `started_at` string, date-time
    - `status` 'queued' | 'running' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'killed', required
    - `status_reason` string: Why a scan was cancelled, stopped or failed.
    - `trigger` 'manual' | 'recheck' | 'monitoring' | 'admin' | 'api', required: Why a scan ran.
  - `monitoring` MonitoringBrief
    - `frequency` 'daily' | 'weekly', required
    - `health` 'healthy' | 'delayed' | 'attention' | 'paused' | 'off', required: healthy; delayed (a scheduled check is waiting on Ironfang's capacity); attention (recent scheduled checks could not complete); paused; off.
    - `next_run_at` string, date-time
    - `state` 'off' | 'pending_first_run' | 'active' | 'paused' | 'paused_verification_lost' | 'paused_authorisation' | 'paused_repeated_failures' | 'paused_by_ironfang', required: off (never switched on, or switched off), pending_first_run, active, paused (by the customer), paused_verification_lost, paused_authorisation, paused_repeated_failures, paused_by_ironfang.
  - `name` string, required: ASCII (punycode) name.
  - `next_scan_at` string, date-time: When the cooldown ends.
  - `open_findings` SeverityCounts, required
    - `critical` integer, required
    - `high` integer, required
    - `info` integer, required
    - `low` integer, required
    - `medium` integer, required
  - `scan_blocked_reason` 'verification_required' | 'authorisation_required' | 'policy_outdated' | 'scan_in_progress' | 'scan_cooldown' | 'daily_limit_reached' | 'organisation_suspended' | 'scans_paused' | 'security_disabled': Why a scan cannot start now.
  - `verification_status` 'waiting' | 'checking' | 'verified' | 'failed' | 'expired' | 'lapsed', required
  - `authorisation` Authorisation
    - `accepted_at` string, date-time, required
    - `accepted_by` Person, required
      - `label` string, required
    - `current` boolean, required: False when the policy has changed and must be confirmed again.
    - `id` string, uuid, required
    - `policy_version` string, required
    - `statement` string, required
    - `statement_version` string, required
  - `discoveries` integer, required: Number of discovered names.
  - `verification` Verification, required
    - `checks` integer, required: How many times the record has been looked up.
    - `dns_provider` DnsProvider
      - `help_url` string, uri
      - `id` string, required: e.g. cloudflare, route53, godaddy, namecheap, azure, google, other
      - `name` string, required
    - `expires_at` string, date-time
    - `failure_reason` string
    - `last_checked_at` string, date-time
    - `manual_check_available_at` string, date-time
    - `method` 'dns_txt', required
    - `next_check_at` string, date-time
    - `observed_values` string[]: TXT values seen at the record name on the last lookup, to help troubleshooting.
    - `record` VerificationRecord, required
      - `host_label` string, required: The name relative to the domain, for providers that append the domain.
      - `name` string, required: Fully qualified record name.
      - `type` 'TXT', required
      - `value` string, required
    - `status` 'waiting' | 'checking' | 'verified' | 'failed' | 'expired' | 'lapsed', required
    - `verified_at` string, date-time

## Other responses

- `404`: An error.
- `409`: An error.
- `422`: An error.
- `default`: An error.

---

[API](https://skmtc.dev/ironfang/apis/ironfang-security-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-security-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-security-api/revisions/73bd66283d59?raw)