# Record an authorization > The authorizations.create operation: POST /api/v1/authorizations in the REST API and the authorizations_create tool in the MCP server. 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`](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. | 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), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`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).