# Authorizations tools > MCP tools for Authorizations: authorizations_create, authorizations_documents_upload, authorizations_get, authorizations_list, authorizations_revoke, authorizations_update. - `authorizations_create`: Record an authorization - `authorizations_documents_upload`: Upload an authorization document - `authorizations_get`: Get an authorization - `authorizations_list`: List authorizations - `authorizations_revoke`: Revoke an authorization - `authorizations_update`: Update an authorization ## `authorizations_create` **Record an authorization.** Operation [`authorizations.create`](https://ownrecord.io/docs/reference/authorizations-create.md) · Legal entity level · permission `tasks:write` · risk tier `compliance` · since M10 Records who is legally allowed to act for the legal entity with a tax authority (spec §41.5): the holder (a person, a firm or an installed app), the kind (an employee with an eID, a power of attorney, a tax or fiscal representative, an API OAuth grant), the regimes and portals it covers, its validity, the signed document (`authorizations.documents.upload` first) and non-secret access notes. Submitting a `*.submit` task references a valid one. Ownrecord records the chain; it doesn't grant or verify legal authority. **Never store credentials**: portal passwords, PINs, eIDs and certificates stay in the holder's own vault. Text that looks like one is refused (`authorization_secret_refused`). Compliance tier (spec §41.4): an agent's call needs approval under the default policy. Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `regimeIds` | array of string | yes | The regimes it covers, e.g. `EU_OSS_UNION`. (1–50 items) | | `holder` | object | yes | Who may act: a person, a firm, or an installed app. | | `kind` | one of `employee_eid`, `power_of_attorney`, `tax_representative`, `fiscal_representative`, `api_oauth` | yes | The kind of authority. | | `documentFileId` | ID (`file_…`) | no | The signed document, uploaded with `authorizations.documents.upload`. | | `validFrom` | date-time (ISO 8601) | yes | From when it is valid (ISO 8601). | | `validTo` | date-time (ISO 8601) | no | Until when it is valid (ISO 8601); none: open-ended. | | `portals` | array of string | no | The tax portals it covers (names or URLs). (at most 20 items) | | `accessNotes` | object | no | Non-secret access notes: the method, the renewal date, who holds access. Never credentials. | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed, or `validTo` isn't after `validFrom`. - [`authorization_secret_refused`](https://ownrecord.io/docs/reference/errors.md#authorization_secret_refused): A text field looks like a credential (`param` names it). - [`authorization_document_not_found`](https://ownrecord.io/docs/reference/errors.md#authorization_document_not_found): `documentFileId` isn't an authorization document of this entity. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage this entity's tasks and authorizations. ### Example **Our tax manager files with her eID** Arguments: ```json { "regimeIds": ["EU_OSS_UNION"], "holder": { "type": "person", "name": "Ana Horvat", "contact": "ana.horvat@example.com" }, "kind": "employee_eid", "validFrom": "2026-01-01T00:00:00.000Z", "validTo": "2027-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." }, "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```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": "2027-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-01-05T10:00:00.000Z", "version": 1 } ``` ## `authorizations_documents_upload` **Upload an authorization document.** Operation [`authorizations.documents.upload`](https://ownrecord.io/docs/reference/authorizations-documents-upload.md) · Legal entity level · permission `tasks:write` · risk tier `write` · since M10 Uploads the signed document behind an authorization: a power of attorney, the appointment of a tax or fiscal representative. Send the file base64-encoded in `content`: a PDF, PNG, JPEG or WebP file of at most 3 MB, with its `filename`. It is stored privately (spec §7.10) and returned with its `file_…` ID: pass it as `documentFileId` to `authorizations.create` or `authorizations.update`. Never upload credentials (key files, certificates with their private key, password lists). Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | ----------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `content` | string | yes | The file's bytes, base64-encoded: a PDF, PNG, JPEG or WebP file of at most 3 MB. (1–4294304 characters) | | `filename` | string | no | The file's name. (1–200 characters) | | `contentType` | one of `application/pdf`, `image/png`, `image/jpeg`, `image/webp` | no | The file's type. Optional: it is read from the file, and must agree when given. | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): The content isn't a PDF, PNG, JPEG or WebP file of at most 3 MB. - [`upstream_timeout`](https://ownrecord.io/docs/reference/errors.md#upstream_timeout): The file store didn't answer in time; nothing was recorded. Retry. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage this entity's tasks and authorizations. ### Example **Upload a power of attorney** Arguments: ```json { "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCnRyYWlsZXIKPDwvUm9vdCAxIDAgUj4+CiUlRU9GCg==", "filename": "power-of-attorney.pdf", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```json { "id": "file_01m4ttwd3veh9apbewxheq5xa2", "object": "authorization_document", "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4", "filename": "power-of-attorney.pdf", "contentType": "application/pdf", "size": 52114, "sha256": "8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c", "createdAt": "2026-01-05T09:58:00.000Z" } ``` ## `authorizations_get` **Get an authorization.** Operation [`authorizations.get`](https://ownrecord.io/docs/reference/authorizations-get.md) · Legal entity level · permission `tasks:read` · risk tier `read` · since M10 Returns one authorization of the legal entity: who may act, the kind of authority, the regimes and portals it covers, its validity (`status` as of now), its document and the non-secret access notes. Ownrecord records authorizations; it can't verify that they are legally valid. Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`atz_…`) | yes | – | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Read-only:** changes nothing; `idempotency_key` is ignored. ### Errors - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No authorization with this ID for this entity in this mode. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this entity's tasks and authorizations. ### Example **An employee with an eID** Arguments: ```json { "id": "atz_01m4ttwd3veh9apbewxheq5xa3", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy" } ``` Result `output`: ```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": "2027-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-01-05T10:00:00.000Z", "version": 1 } ``` ## `authorizations_list` **List authorizations.** Operation [`authorizations.list`](https://ownrecord.io/docs/reference/authorizations-list.md) · Legal entity level · permission `tasks:read` · risk tier `read` · since M10 Lists who may act for the legal entity with tax authorities in the mode of the request, newest first: the holder (a person, a firm or an installed app), the kind of authority, the regimes and portals it covers, its validity and document. `status` is as of now (`expired` once past `validTo`). Filter by `regimeId`, or `validNow: true` for the ones a submission can reference now. Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ---------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `limit` | integer | no | (1–100) | | `starting_after` | ID (`atz_…`) | no | – | | `regimeId` | string | no | (1–100 characters) | | `validNow` | boolean or string | no | – | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Read-only:** changes nothing; `idempotency_key` is ignored. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A filter or pagination value is invalid. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see this entity's tasks and authorizations. ### Example **Who may file the OSS return now** Arguments: ```json { "regimeId": "EU_OSS_UNION", "validNow": true, "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy" } ``` Result `output`: ```json { "object": "list", "data": [ { "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": "2027-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-01-05T10:00:00.000Z", "version": 1 } ], "has_more": false, "next_cursor": null } ``` ## `authorizations_revoke` **Revoke an authorization.** Operation [`authorizations.revoke`](https://ownrecord.io/docs/reference/authorizations-revoke.md) · Legal entity level · permission `tasks:write` · risk tier `compliance` · since M10 Ends an authorization at once, for example when the person left or the power of attorney was withdrawn: submissions can't reference it any more. It stays in the record (with the reason) for the audit chain of what was submitted under it. Revoking twice is refused (`authorization_status_invalid`). Compliance tier (spec §41.4): an agent's call needs approval under the default policy. Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: false` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`atz_…`) | yes | – | | `reason` | string | yes | (1–2000 characters) | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): No reason. - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No authorization with this ID for this entity in this mode. - [`authorization_status_invalid`](https://ownrecord.io/docs/reference/errors.md#authorization_status_invalid): It is already revoked. - [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): It changed at the same moment. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage this entity's tasks and authorizations. ### Example **Ana left the company** Arguments: ```json { "id": "atz_01m4ttwd3veh9apbewxheq5xa3", "reason": "Ana left the company on 31 October.", "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```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": "2027-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": "revoked", "revokedAt": "2026-11-08T09:15:00.000Z", "revocationReason": "Ana left the company on 31 October.", "createdAt": "2026-01-05T10:00:00.000Z", "updatedAt": "2026-11-08T09:15:00.000Z", "version": 2 } ``` ## `authorizations_update` **Update an authorization.** Operation [`authorizations.update`](https://ownrecord.io/docs/reference/authorizations-update.md) · Legal entity level · permission `tasks:write` · risk tier `compliance` · since M10 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. Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false` ### Arguments | Argument | Type | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | ID (`atz_…`) | yes | – | | `regimeIds` | array of string | no | The regimes it covers, e.g. `EU_OSS_UNION`. (1–50 items) | | `holder` | object | no | Who may act: a person, a firm, or an installed app. | | `kind` | one of `employee_eid`, `power_of_attorney`, `tax_representative`, `fiscal_representative`, `api_oauth` | no | The kind of authority. | | `documentFileId` | ID (`file_…`) or null | no | – | | `validFrom` | date-time (ISO 8601) | no | From when it is valid (ISO 8601). | | `validTo` | date-time (ISO 8601) or null | no | – | | `portals` | array of string | no | The tax portals it covers (names or URLs). (at most 20 items) | | `accessNotes` | object or null | no | – | | `expectedVersion` | integer | no | (1–9007199254740991) | | `entity_id` | ID (`ent_…`) | no | The legal entity to act on (ent\_…), inside your API key's reach. Needed with an organization key; entity and brand keys act on their own entity. | | `idempotency_key` | string | no | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) | | `dry_run` | boolean | no | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`) | - **Legal entity:** pass `entity_id` with an organization key; entity and brand keys act on their own entity. - **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours). - **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back. ### Errors - [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is malformed, or `validTo` isn't after `validFrom`. - [`authorization_secret_refused`](https://ownrecord.io/docs/reference/errors.md#authorization_secret_refused): A text field looks like a credential (`param` names it). - [`authorization_document_not_found`](https://ownrecord.io/docs/reference/errors.md#authorization_document_not_found): `documentFileId` isn't an authorization document of this entity. - [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required): The request names no legal entity. - [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't manage this entity's tasks and authorizations. - [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No authorization with this ID for this entity in this mode. - [`authorization_status_invalid`](https://ownrecord.io/docs/reference/errors.md#authorization_status_invalid): The authorization is revoked. - [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): It changed since `expectedVersion`, or at the same moment. ### Example **Extend it by a year** Arguments: ```json { "id": "atz_01m4ttwd3veh9apbewxheq5xa3", "validTo": "2028-12-31T23:00:00.000Z", "expectedVersion": 1, "entity_id": "ent_01jbx4m3v8e9t0s6k2c5n7q1wy", "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21" } ``` Result `output`: ```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 } ```