# Upload an authorization document

> The authorizations.documents.upload operation: POST /api/v1/authorizations/documents in the REST API and the authorizations_documents_upload tool in the MCP server.

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).

## At a glance

- **REST:** `POST /api/v1/authorizations/documents`
- **MCP tool:** `authorizations_documents_upload`
- **Operation ID:** `authorizations.documents.upload`
- **Scope:** Legal entity
- **Permission:** `tasks:write`
- **Risk tier:** `write`
- **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                                                                      |
| ------------- | ----------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------- |
| `content`     | string                                                            | Yes      | The file's bytes, base64-encoded: a PDF, PNG, JPEG or WebP file of at most 3 MB. |
| `filename`    | string                                                            | No       | The file's name.                                                                 |
| `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.  |

## Response

`201 Created` with a JSON object:

| Field         | Type                       | Description |
| ------------- | -------------------------- | ----------- |
| `id`          | `file_…` ID                |             |
| `object`      | `"authorization_document"` |             |
| `entityId`    | `ent_…` ID                 |             |
| `filename`    | string or null             |             |
| `contentType` | string                     |             |
| `size`        | integer (at least 0)       |             |
| `sha256`      | string                     |             |
| `createdAt`   | date-time                  |             |

## Examples

### Upload a power of attorney

```http
POST /api/v1/authorizations/documents
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCnRyYWlsZXIKPDwvUm9vdCAxIDAgUj4+CiUlRU9GCg==",
  "filename": "power-of-attorney.pdf"
}
```

Response (`201`):

```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"
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                               | What to do                                                                                                                                         |
| -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | The content isn't a PDF, PNG, JPEG or WebP file of at most 3 MB.   | Fix the fields listed in `details.issues` and send the request again.                                                                              |
| [`upstream_timeout`](https://ownrecord.io/docs/reference/errors.md#upstream_timeout)   | 502         | The file store didn't answer in time; nothing was recorded. Retry. | Retry the request with the same Idempotency-Key after a short wait.                                                                                |
| [`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).