# Update an authorization

> The authorizations.update operation: PATCH /api/v1/authorizations/{id} in the REST API and the authorizations_update tool in the MCP server.

Changes an authorization: the regimes and portals it covers, its validity (extend `validTo`, or `null` for
open-ended), its document (`null` removes it), the holder's details or the non-secret access notes. A
revoked authorization doesn't change (`authorization_status_invalid`); record a new one. Never store
credentials (`authorization_secret_refused`).

Compliance tier (spec §41.4): an agent's call needs approval under the default policy.

## At a glance

- **REST:** `PATCH /api/v1/authorizations/{id}`
- **MCP tool:** `authorizations_update`
- **Operation ID:** `authorizations.update`
- **Scope:** Legal entity
- **Permission:** `tasks:write`
- **Risk tier:** `compliance`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` optional
- **Modes:** Test and live
- **Authentication:** API key with the `tasks:write` scope
- **Since:** M10

## Request

### Path parameters

| Field | Type       | Description |
| ----- | ---------- | ----------- |
| `id`  | `atz_…` ID |             |

### Body

A JSON object (`Content-Type: application/json`):

| Field                      | Type                                                                                                   | Required | Description                                         |
| -------------------------- | ------------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------- |
| `regimeIds`                | array of string                                                                                        | No       | The regimes it covers, e.g. `EU_OSS_UNION`.         |
| `holder`                   | object                                                                                                 | No       | Who may act: a person, a firm, or an installed app. |
| `holder.type`              | one of `person`, `firm`, `app`                                                                         | Yes      |                                                     |
| `holder.name`              | string                                                                                                 | Yes      |                                                     |
| `holder.contact`           | string                                                                                                 | No       |                                                     |
| `holder.appInstallationId` | `ains_…` ID                                                                                            | No       |                                                     |
| `kind`                     | one of `employee_eid`, `power_of_attorney`, `tax_representative`, `fiscal_representative`, `api_oauth` | No       | The kind of authority.                              |
| `documentFileId`           | `file_…` ID or null                                                                                    | No       |                                                     |
| `validFrom`                | date-time                                                                                              | No       | From when it is valid (ISO 8601).                   |
| `validTo`                  | date-time or null                                                                                      | No       |                                                     |
| `portals`                  | array of string                                                                                        | No       | The tax portals it covers (names or URLs).          |
| `accessNotes`              | object or null                                                                                         | No       |                                                     |
| `expectedVersion`          | integer (at least 1)                                                                                   | No       |                                                     |

## Response

`200 OK` with a JSON object:

| Field                      | Type                                                                                                   | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------ | ----------- |
| `id`                       | `atz_…` ID                                                                                             |             |
| `object`                   | `"authorization"`                                                                                      |             |
| `entityId`                 | `ent_…` ID                                                                                             |             |
| `livemode`                 | boolean                                                                                                |             |
| `regimeIds`                | array of string                                                                                        |             |
| `holder`                   | object                                                                                                 |             |
| `holder.type`              | one of `person`, `firm`, `app`                                                                         |             |
| `holder.name`              | string                                                                                                 |             |
| `holder.contact`           | string or null                                                                                         |             |
| `holder.appInstallationId` | `ains_…` ID or null                                                                                    |             |
| `kind`                     | one of `employee_eid`, `power_of_attorney`, `tax_representative`, `fiscal_representative`, `api_oauth` |             |
| `documentFileId`           | `file_…` ID or null                                                                                    |             |
| `validFrom`                | date-time                                                                                              |             |
| `validTo`                  | date-time or null                                                                                      |             |
| `portals`                  | array of string                                                                                        |             |
| `accessNotes`              | object or null                                                                                         |             |
| `status`                   | one of `active`, `expired`, `revoked`, `not_yet_valid`                                                 |             |
| `revokedAt`                | date-time or null                                                                                      |             |
| `revocationReason`         | string or null                                                                                         |             |
| `createdAt`                | date-time                                                                                              |             |
| `updatedAt`                | date-time                                                                                              |             |
| `version`                  | integer (at least 1)                                                                                   |             |

## Examples

### Extend it by a year

```http
PATCH /api/v1/authorizations/atz_01m4ttwd3veh9apbewxheq5xa3
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "validTo": "2028-12-31T23:00:00.000Z",
  "expectedVersion": 1
}
```

Response (`200`):

```json
{
  "id": "atz_01m4ttwd3veh9apbewxheq5xa3",
  "object": "authorization",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "livemode": true,
  "regimeIds": ["EU_OSS_UNION"],
  "holder": {
    "type": "person",
    "name": "Ana Horvat",
    "contact": "ana.horvat@example.com",
    "appInstallationId": null
  },
  "kind": "employee_eid",
  "documentFileId": null,
  "validFrom": "2026-01-01T00:00:00.000Z",
  "validTo": "2028-12-31T23:00:00.000Z",
  "portals": ["Croatian Tax Administration OSS portal (ePorezna)"],
  "accessNotes": {
    "method": "eid",
    "renewalDueAt": "2027-11-30T23:00:00.000Z",
    "notes": "Ana signs in with her personal eID card."
  },
  "status": "active",
  "revokedAt": null,
  "revocationReason": null,
  "createdAt": "2026-01-05T10:00:00.000Z",
  "updatedAt": "2026-11-08T09:15:00.000Z",
  "version": 2
}
```

## Errors

| Code                                                                                                                 | HTTP status | When                                                             | What to do                                                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)                               | 400         | A field is malformed, or `validTo` isn't after `validFrom`.      | Fix the fields listed in `details.issues` and send the request again.                                                                                                           |
| [`authorization_secret_refused`](https://ownrecord.io/docs/reference/errors.md#authorization_secret_refused)         | 400         | A text field looks like a credential (`param` names it).         | Keep passwords, PINs, eIDs and certificates in your own vault. Record only non-secret notes: the access method, who holds access and the renewal date. `param` names the field. |
| [`authorization_document_not_found`](https://ownrecord.io/docs/reference/errors.md#authorization_document_not_found) | 400         | `documentFileId` isn't an authorization document of this entity. | Upload the signed document with `authorizations.documents.upload` and pass its `file_…` ID as `documentFileId`.                                                                 |
| [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required)                                     | 400         | The request names no legal entity.                               | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).                              |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)                               | 403         | You can't manage this entity's tasks and authorizations.         | Ask an organization owner or admin for a role or scope that allows this action.                                                                                                 |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)                             | 404         | No authorization with this ID for this entity in this mode.      | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                                                            |
| [`authorization_status_invalid`](https://ownrecord.io/docs/reference/errors.md#authorization_status_invalid)         | 409         | The authorization is revoked.                                    | A revoked authorization doesn't change. Record a new one with `authorizations.create`.                                                                                          |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)                                 | 409         | It changed since `expectedVersion`, or at the same moment.       | Fetch the object again and retry the change.                                                                                                                                    |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).