---
title: "Submit the card's authentication certificate; receive the DTBS + challenge"
method: POST
path: "/auth/{requestId}/certificate"
tags: ["Auth"]
---

# Submit the card's authentication certificate; receive the DTBS + challenge

`POST /auth/{requestId}/certificate`

## Request

- Base URL: `https://atk.tvarka.pro/v1`
- URL: `https://atk.tvarka.pro/v1/auth/{requestId}/certificate`
- Auth: HTTP bearer

Called by the client with `Authorization: Bearer <clientToken>`. The API validates the
certificate (chain, revocation, purpose = authentication, key usage), builds the canonical
challenge, and returns the exact `dtbs` the card must sign plus a single-use `operationToken`.

## Path parameters

- `requestId` string, uuid, required

## Request body

- AuthCertificateSubmit
  - `certificate` string, byte, required: Base64 DER of the card's **authentication** certificate.

## Response `200`

DTBS + challenge + operation token.

- AuthCertificateChallenge
  - `requestId` string, uuid, required
  - `dtbs` string, byte, required: Base64 of the exact digest the card must sign (ECDSA prehashed). Built as the `atk-auth-v1` construction - see `Challenge`.
  - `dtbsHashAlgOid` '2.16.840.1.101.3.4.2.1' | '2.16.840.1.101.3.4.2.2', required: Digest algorithm OID, curve-matched. SHA-256 = 2.16.840.1.101.3.4.2.1; SHA-384 = 2.16.840.1.101.3.4.2.2.
  - `operationToken` string, required: Single-use JWT bound to {tenant, requestId, purpose, certFp, dtbsHash}; the nonce is bound indirectly via dtbs. Returned at /complete.
  - `verificationCode` string
  - `challenge` AuthChallenge, required: Canonical `atk-auth-v1` anti-relay challenge. The server issues `nonce`; `dtbs` returned above = `HASH( HASH(utf8(audience_origin)) || HASH(utf8(nonce)) )` with `HASH` matched to the auth-key curve (P-256 -> SHA-256, P-384 -> SHA-384). Versioned - future profiles never reinterpret an existing `dtbs`. This binding is what a relying party (e.g. ePaslaugos) audits.
    - `profile` 'atk-auth-v1', required
    - `audience` string, required
    - `nonce` string, required: Server-issued base64url challenge string (44-128 chars).
  - `cert` object, required: Echoes only the parsed `subject` (the client itself just submitted the DER). The certificate DER is returned at `/complete` and on GET once done.
    - `subject` AuthCertSubject, required: Selected subject fields from the certificate. `serialNumber` holds `PNOLT-<personal code>`.
      - `serialNumber` string
      - `givenName` string
      - `sn` string: Surname.
      - `cn` string
      - `c` string

## Other responses

- `401`: Missing/invalid credentials or client token.
- `403`: Authorized but not permitted (origin/format/tenant).
- `404`: Unknown request.
- `409`: State/idempotency conflict (spent operation token, identity swap, terminal request).
- `422`: Semantic reject (cert purpose/chain/revocation, dtbs mismatch, bad signature).

---

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