Record an authorization · Ownrecord docs

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.

At a glance

REST: POST /api/v1/authorizations
MCP tool: authorizations_create
Operation ID: authorizations.create
Scope: Legal entity
Permission: tasks:write
Risk tier: compliance
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the tasks:write scope
Since: M10

Request

Body

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

Field	Type	Required	Description
`regimeIds`	array of string	Yes	The regimes it covers, e.g. `EU_OSS_UNION`.
`holder`	object	Yes	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`	Yes	The kind of authority.
`documentFileId`	`file_…` ID	No	The signed document, uploaded with `authorizations.documents.upload`.
`validFrom`	date-time	Yes	From when it is valid (ISO 8601).
`validTo`	date-time	No	Until when it is valid (ISO 8601); none: open-ended.
`portals`	array of string	No	The tax portals it covers (names or URLs).
`accessNotes`	object	No	Non-secret access notes: the method, the renewal date, who holds access. Never credentials.
`accessNotes.method`	one of `eid`, `certificate`, `api_oauth`, `portal_account`, `other`	No
`accessNotes.renewalDueAt`	date-time	No
`accessNotes.notes`	string	No

Response

201 Created 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

Our tax manager files with her eID

HTTP

POST /api/v1/authorizations
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/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."
  }
}

Response (201):

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
}

Errors

Code	HTTP status	When	What to do
`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`	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`	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`	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`	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.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Our tax manager files with her eID#

Errors#