---
title: "Create a signing request (server-to-server)"
method: POST
path: "/sign/requests"
tags: ["Sign"]
---

# Create a signing request (server-to-server)

`POST /sign/requests`

## Request

- Base URL: `https://atk.tvarka.pro/v1`
- URL: `https://atk.tvarka.pro/v1/sign/requests`
- Auth: HTTP basic

HTTP Basic. Provide the document one of three ways - inline `document` (base64), an allow-listed
`documentRef`, or a bare `hash` (only for `format:"raw"`). Container formats
(pades/asice/adoc) require exactly one of `document` or `documentRef`. PAdES accepts an unsigned
or already-signed PDF; ASiC-E/ADOC accept either a PDF (Tvarka constructs a new single-payload
container) or an existing valid container, which is treated as an opaque whole and receives one
additional signature without payload or attachment edits. Physical requests return a client
token; NFC returns a pairing hint.

## Request body

- union: The ATK card signs every listed format, by physical reader or NFC.
  - object
    - `format` 'raw', required
    - `method` 'physical' | 'nfc', required
    - `hash` string, byte, required
    - `hashAlgOid` '2.16.840.1.101.3.4.2.1' | '2.16.840.1.101.3.4.2.2', required: SHA-256 / SHA-384 OID, curve-matched.
    - `filename` string
    - `mimeType` string
    - `message` string
    - `externalId` string
    - `webhookUrl` string, uri
  - object
    - `document` unknown, required
  - object
    - `documentRef` unknown, required

## Response `202`

Request created; awaiting the ATK client authorization.

- SignSignRequestCreated: Physical requests return `clientToken`; NFC returns `pairing`.
  - `requestId` string, uuid, required
  - `method` 'physical' | 'nfc', required: physical = desktop reader; nfc = phone tap.
  - `verificationCode` string, required: NFC anti-relay confirmation code.
  - `clientToken` string
  - `status` 'pending' | 'awaitingCard' | 'awaitingCredentials' | 'finalizing' | 'done' | 'cancelled' | 'timeout' | 'deviceError' | 'pinBlocked' | 'cardRemoved' | 'certInvalid', required: Non-terminal - pending/awaitingCard/awaitingCredentials/finalizing. Terminal success - done. Terminal failure - cancelled/timeout/deviceError/pinBlocked/cardRemoved/certInvalid. Validation failure is on the `validation` axis, NOT here.
  - `expiresAt` string, date-time, required
  - `pairing` SignPairingHint
    - `pairingUrl` string, uri
    - `deepLink` string
    - `qrPayload` string

## Other responses

- `400`: Malformed input (e.g. container format without document, hash without raw).
- `401`: Missing/invalid credentials or client token.
- `403`: Format not allowed / origin not allowed / tenant suspended.
- `413`: Document exceeds the tenant's max size.
- `429`: Too many requests.
- `503`: Validation/TSA/revocation dependency failed transiently; retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/tvarka/apis/tvarka-atk-api.md) · [All operations](https://skmtc.dev/tvarka/apis/tvarka-atk-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tvarka/apis/tvarka-atk-api/revisions/2ab888b16069?raw)