Authorizations tools · Ownrecord docs

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 · 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: A field is malformed, or validTo isn't after validFrom.
authorization_secret_refused: A text field looks like a credential (param names it).
authorization_document_not_found: documentFileId isn't an authorization document of this entity.
scope_required: The request names no legal entity.
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 · 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: The content isn't a PDF, PNG, JPEG or WebP file of at most 3 MB.
upstream_timeout: The file store didn't answer in time; nothing was recorded. Retry.
scope_required: The request names no legal entity.
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 · 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: No authorization with this ID for this entity in this mode.
scope_required: The request names no legal entity.
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 · 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: A filter or pagination value is invalid.
scope_required: The request names no legal entity.
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 · 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: No reason.
resource_not_found: No authorization with this ID for this entity in this mode.
authorization_status_invalid: It is already revoked.
version_conflict: It changed at the same moment.
scope_required: The request names no legal entity.
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 · 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: A field is malformed, or validTo isn't after validFrom.
authorization_secret_refused: A text field looks like a credential (param names it).
authorization_document_not_found: documentFileId isn't an authorization document of this entity.
scope_required: The request names no legal entity.
permission_denied: You can't manage this entity's tasks and authorizations.
resource_not_found: No authorization with this ID for this entity in this mode.
authorization_status_invalid: The authorization is revoked.
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
}

authorizations_create#

Arguments#

Errors#

Example#

authorizations_documents_upload#

Arguments#

Errors#

Example#

authorizations_get#

Arguments#

Errors#

Example#

authorizations_list#

Arguments#

Errors#

Example#

authorizations_revoke#

Arguments#

Errors#

Example#

authorizations_update#

Arguments#

Errors#

Example#

`authorizations_create`

Arguments

Errors

Example

`authorizations_documents_upload`

Arguments

Errors

Example

`authorizations_get`

Arguments

Errors

Example

`authorizations_list`

Arguments

Errors

Example

`authorizations_revoke`

Arguments

Errors

Example

`authorizations_update`

Arguments

Errors

Example