Create Authorisation

Record the operator's explicit acknowledgement of §9 step 3 of the EUDR Compliance Process — "I authorize Epoch to file this DDS to TRACES on my behalf." Without one on file for the record's current version, the on-behalf-of submit route (Submit DDS with mode: "submit") refuses to file (422 with authorization_missing blocker).

This endpoint records consent only — it never writes submission metadata. Edit the version's submission metadata via Update DDS Record (PATCH) before authorising; the Submit DDS one-call flow accepts the same editable subset at filing time. (An earlier revision accepted an optional submission_metadata block here; it was removed so a re-grant can never overwrite staged fields — a stale client still sending it gets a normal grant with the unknown key stripped.)

Path params

Param	Description
`recordId`	DDS record id

Request body

{
  "data": {
    "type": "dds_authorization",
    "attributes": {
      "confirmed": true,
      "text_version": "v2",
      "signee": "Jane Operator"
    }
  }
}

Field	Type	Notes
`confirmed`	literal `true`	The tick-box action. A boolean `false` or any non-true value fails parse with `400 BAD_REQUEST`.
`text_version`	string	Must equal the server's current version (today: `"v2"`). Stale versions return `400 AUTHORIZATION_TEXT_VERSION_MISMATCH` with `details = { expected, received }`.
`signee`	string \| omitted	Optional human-readable name of the person ticking the box. 1–200 chars (trimmed). Stored on the audit event's `payload.signee` so the inspector view can surface who on the operator side acknowledged, beyond the API-key identity.

Response shape

Wire type: "dds_authorization". attributes carry the version the authorisation is pinned to + the audit-event metadata:

Field	Source
`version_id` / `version_number`	The record's current version at grant time
`text_version`	Echoes the body's `text_version`
`granted_at`	Audit event `occurred_at` (ISO 8601 UTC)
`granted_by_user_id`	API key user (null on org-level keys)
`granted_by_org_id`	The calling org
`signee`	The body's `signee`, or null if omitted

Idempotency

Posting twice for the same (version, text_version) returns the existing row with 200 OK (no duplicate audit events). The idempotent check intentionally ignores signee — a re-tick by a different signee for the same text version collapses to the original row (the first acknowledgement is the legally binding one).

Errors

Status	Code	When
400	`BAD_REQUEST`	Body fails Zod validation (`confirmed !== true`, missing `text_version`, etc.)
400	`AUTHORIZATION_TEXT_VERSION_MISMATCH`	`text_version` is not the server's current version. `details = { expected, received }`.
401	`UNAUTHORIZED`	Missing/invalid API key
404	`NOT_FOUND`	Record isn't visible to the caller
409	`CONFLICT`	The current version already has a submit-lifecycle event in the audit log; authorisation window is closed

Required scope: ingestions:write