# pasteToPrint Document API – bearer tokeny a TTL

Document API v2 podporuje voliteľné bearer tokeny oddelené od používateľských
účtov pasteToPrint. Bez tokenu ostáva verejný anonymný režim. Token neposielajte
v URL; patrí výhradne do hlavičky `Authorization`.

## Vytvorenie tokenu

```bash
php scripts/generate-document-api-token.php my-ai-client standard document:create
```

Príkaz zobrazí náhodný bearer token iba raz a konfiguračný záznam s jeho
SHA-256 hashom. Na server sa neukladá pôvodný token.

Konfiguračný súbor má formát:

```json
{
  "version": 1,
  "tokens": [
    {
      "id": "my-ai-client",
      "tokenHash": "64-znakovy-sha256-hash",
      "scopes": [
        "document:create"
      ],
      "tier": "standard",
      "enabled": true
    }
  ]
}
```

Cestu nastavte cez `PASTETOPRINT_DOCUMENT_API_TOKENS_FILE`. Súbor musí byť
čitateľný PHP procesom a musí ležať mimo verejného webrootu aj mimo dočasného
úložiska agent importov. Alternatívne možno rovnaký JSON vložiť do
`PASTETOPRINT_DOCUMENT_API_TOKENS_JSON`.

## Použitie

```http
POST /api/v2/documents HTTP/1.1
Authorization: Bearer ptp_ai_...
Idempotency-Key: order-2026-07-20-001
X-Document-TTL: 86400
Content-Type: application/json
```

`X-Document-TTL` je voliteľný počet sekúnd. Odpoveď vráti skutočnú hodnotu
v `sessionTtlSeconds` a hlavičke `X-Document-TTL-Applied`.

## TTL a rate-limit tiery

| Tier | Predvolená TTL | Maximálna TTL | Nové session / 10 min |
|---|---:|---:|---:|
| `anonymous` | 15 min | 15 min | 12 |
| `standard` | 24 h | 24 h | 120 |
| `trusted` | 24 h | 7 dní | 600 |

Minimálna vyžiadaná TTL je 60 sekúnd. Replay existujúcej idempotentnej
požiadavky nevytvára novú session a nespotrebuje ďalší rate-limit.

## Scopes

Kontrakt konfigurácie pozná:

- `document:create`,
- `document:read`,
- `document:update`,
- `document:delete`.

`POST /api/v2/documents` vyžaduje `document:create`. Operácie nad
`/api/v2/documents/{sessionId}` vyžadujú podľa metódy `document:read`,
`document:update` alebo `document:delete`; rovnaký vlastník musí session aj
vytvoriť. Upload session assetu vyžaduje `document:update`.

Namiesto API bearer tokenu možno pre jednu konkrétnu session použiť tajný
`sessionToken` v hlavičke `X-Session-Token`. Tento token sa vracia pri vytvorení
session, neukladá sa do používateľských odkazov a neoprávňuje k iným session.

Vrátené `editorUrl` a `viewUrl` sú dva samostatné dočasné capability odkazy
určené pre používateľa; pri otvorení nevyžadujú bearer token. Zaobchádzajte
s nimi ako s citlivými odkazmi a nezverejňujte ich.

## Bezpečnostné správanie

- chybná alebo vypnutá hodnota tokenu vráti `401 invalid_token`,
- chýbajúci scope vráti `403 insufficient_scope`,
- TTL nad limitom tieru vráti `403 ttl_not_allowed`,
- idempotencia tokenového klienta je viazaná na jeho `id`, nie IP adresu,
- token možno okamžite zneplatniť nastavením `enabled: false` alebo odstránením
  z konfigurácie,
- raw tokeny, hlavičku `Authorization` ani obsah dokumentov nezapisujte do logov.