---
title: "Create an authentication request (server-to-server)"
method: POST
path: "/auth/requests"
tags: ["Auth"]
---

# Create an authentication request (server-to-server)

`POST /auth/requests`

## Request

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

Called by the provider's backend with HTTP Basic (`keyId:keySecret`). `audience` must be an
exact origin on the provider's allow-list. Physical requests return a short-lived `clientToken`;
NFC requests return a pairing hint.

## Request body

- AuthAuthRequestCreate
  - `audience` string, required: The relying-party origin (must be exactly on the provider's allow-list), e.g. https://www.epaslaugos.lt.
  - `method` 'physical' | 'nfc', required: physical = desktop reader; nfc = phone tap.
  - `message` string: Optional short message the client may display to the user.
  - `externalId` string: Provider's own correlation id (echoed back, deduped).
  - `webhookUrl` string, uri: Optional public HTTPS webhook for the terminal status; private/non-global destinations are rejected.

## Response `202`

Request created; awaiting the ATK client authorization.

- AuthAuthRequestCreated: Physical requests return `clientToken`; NFC requests return `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: Scoped bearer JWT for physical-card `/certificate` + `/complete`.
  - `status` 'pending' | 'awaitingCard' | 'awaitingCredentials' | 'finalizing' | 'done' | 'cancelled' | 'timeout' | 'deviceError' | 'pinBlocked' | 'cardRemoved' | 'certInvalid', required: Flat request status. Non-terminal - `pending`, `awaitingCard`, `awaitingCredentials`, `finalizing`. Terminal success - `done`. Terminal failure - `cancelled`/`timeout`/`deviceError`/`pinBlocked`/`cardRemoved`/`certInvalid`. `awaitingCredentials` is SDK-reported (CAN/PIN entry is out-of-band).
  - `expiresAt` string, date-time, required
  - `challengeProfile` 'atk-auth-v1'
  - `nonce` string: Server-minted challenge nonce (see `Challenge`), so the provider backend can re-derive `dtbs` and verify `sig` independently - no device relay needed.
  - `pairing` AuthPairingHint
    - `pairingUrl` string, uri
    - `deepLink` string
    - `qrPayload` string

## Other responses

- `400`: Malformed input.
- `401`: Missing/invalid credentials or client token.
- `403`: Authorized but not permitted (origin/format/tenant).
- `429`: Too many requests.
- `503`: A required backing or erasure service is temporarily unavailable.

---

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