# Change the Address Book Settings

Raise a protection at once; lower one through an approval.

## Overview

- Send what changes: `coolingPeriodSeconds` (0 to `2592000`, 30 days), `proofRequired`, `oneTimeAddresses`. A field left out keeps its value; an empty body answers `400` `ADDRESS_BOOK_REQUEST_INVALID`.
- **`200`, `state` `applied`**: the change raises or keeps every protection, and applies now — a longer cooling period, the proof required, one-time addresses off.
- **`202`, `state` `pending`**: it lowers one — a shorter cooling period, the proof no longer required, one-time addresses on — and waits for [its approval](https://docs.aureahub.com/docs/address-book-change-approve.md). Nothing changed yet; `settings.pendingChange` is the change.
- The answer is `{ state, settings, change }`: the settings as they are now, and the change, which is kept in [Setting Changes](https://docs.aureahub.com/docs/address-book-changes-list.md) either way.
- Refused: another change waiting (`409` `ADDRESS_BOOK_SETTINGS_PENDING`, with `details.changeId`); a cooling period under 24 hours on the institutional profile (`400` `ADDRESS_BOOK_COOLING_TOO_SHORT`).
- For `owner`, `tenantadmin` and `non_signing_admin`.

## Endpoint

### `PUT /v1/address-book/settings`

Authentication: bearer token required.

Changes the settings: at once when nothing is lowered, after an approval otherwise.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `coolingPeriodSeconds` | integer | no | 0–2592000 seconds; at least 86400 on the institutional profile |
| `proofRequired` | boolean | no | An external entry is proven before it is approved |
| `oneTimeAddresses` | boolean | no | Operations may also go to addresses outside the book |

**Responses**

`200` Applied

```json
{
  "state": "applied",
  "settings": {
    "mode": "off",
    "enforced": false,
    "settings": { "coolingPeriodSeconds": 86400, "proofRequired": true, "oneTimeAddresses": false },
    "effectiveCoolingPeriodSeconds": 86400,
    "pendingChange": null
  },
  "change": {
    "id": "2e9a7c41-0b5d-4f86-a3c2-9d1e8b7f6a05",
    "coolingPeriodSeconds": null,
    "proofRequired": true,
    "oneTimeAddresses": null,
    "lowers": false,
    "status": "applied",
    "requiredApprovals": 0,
    "requestedBy": "6a1c9e3f-2b7d-4f50-8e4a-0c5d3b9f7e12",
    "requestedScope": "tenant",
    "createdAt": "2026-10-08T09:00:00.000Z",
    "decidedBy": "6a1c9e3f-2b7d-4f50-8e4a-0c5d3b9f7e12",
    "decidedScope": "tenant",
    "decidedAt": "2026-10-08T09:00:00.000Z"
  }
}
```

`202` Waits for approval

```json
{
  "state": "pending",
  "settings": {
    "mode": "off",
    "enforced": false,
    "settings": { "coolingPeriodSeconds": 86400, "proofRequired": true, "oneTimeAddresses": false },
    "effectiveCoolingPeriodSeconds": 86400,
    "pendingChange": {
      "id": "5b0d3e92-7c1a-4e68-b4f9-0a2c6d8e1f37",
      "coolingPeriodSeconds": 3600,
      "proofRequired": null,
      "oneTimeAddresses": null,
      "lowers": true,
      "status": "pending",
      "requiredApprovals": 1,
      "requestedBy": "6a1c9e3f-2b7d-4f50-8e4a-0c5d3b9f7e12",
      "requestedScope": "tenant",
      "createdAt": "2026-10-08T09:05:00.000Z",
      "decidedBy": null,
      "decidedScope": null,
      "decidedAt": null
    }
  },
  "change": {
    "id": "5b0d3e92-7c1a-4e68-b4f9-0a2c6d8e1f37",
    "coolingPeriodSeconds": 3600,
    "proofRequired": null,
    "oneTimeAddresses": null,
    "lowers": true,
    "status": "pending",
    "requiredApprovals": 1,
    "requestedBy": "6a1c9e3f-2b7d-4f50-8e4a-0c5d3b9f7e12",
    "requestedScope": "tenant",
    "createdAt": "2026-10-08T09:05:00.000Z",
    "decidedBy": null,
    "decidedScope": null,
    "decidedAt": null
  }
}
```

`409` One waits

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "A change of the settings already waits for its approval: approve, reject or withdraw it first",
  "details": { "code": "ADDRESS_BOOK_SETTINGS_PENDING", "changeId": "5b0d3e92-7c1a-4e68-b4f9-0a2c6d8e1f37" }
}
```

**Example request**

```bash
curl -X PUT https://api.aureahub.com/v1/address-book/settings \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "proofRequired": true }'
```

---

Web version: https://docs.aureahub.com/#address-book-settings-put