Vai al contenuto
IT

REST API v1

Link monouso dal tuo codice.

Crea segreti e richieste dalla tua app, dall’helpdesk o da uno script. L’API è disponibile nei piani Pro e Pro Plus.

Crea una chiave API Piani con API

Autenticazione

Crea una chiave API in Il mio account → API. Inviala nell’intestazione Authorization come token Bearer. Tutte le richieste passano su HTTPS.

Authorization: Bearer kx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GET https://kriptano.com/api/v1/me

Il limite di richieste dipende dal piano (Pro 60/min, Pro Plus 300/min). I segreti creati vengono conteggiati nella quota mensile del piano.

Creare un segreto

Il modo più semplice: invia il testo in chiaro via HTTPS – il server lo cifra con lo stesso algoritmo del browser, non conserva la chiave e restituisce il link completo con la chiave.

curl -X POST https://kriptano.com/api/v1/secrets \
  -H "Authorization: Bearer $KRIPTANO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "User: anna\nPassword: Gx7!pQ2m",
    "expires": 604800,
    "views": 1,
    "passphrase": "",
    "label": "Hosting – client Smith",
    "notify": true
  }'

Risposta (201):

{
  "id": "7GkQ2mPzr9XtWbHa",
  "url": "https://kriptano.com/s/7GkQ2mPzr9XtWbHa/#k9Xv3…Qe1s",
  "status": "active",
  "views": 0,
  "max_views": 1,
  "expires_at": "2026-11-13T09:00:00+00:00"
}
CampoDescrizione
secretTesto segreto (fino a ~90.000 caratteri).
filesFacoltativo: [{"name","type","data"(base64)}] – allegati, se il piano li consente.
expiresDurata in secondi: 3600, 86400, 259200, 604800, 1209600, 2592000, 7776000, 15552000, 31536000 (entro il limite del piano).
viewsNumero di aperture (predefinito 1).
passphraseFacoltativa: passphrase aggiuntiva che il destinatario deve inserire.
labelEtichetta interna (visibile solo a te; non inserire dati segreti).
notifytrue = notifica via e-mail all’apertura del segreto.
uploadsFacoltativo: [{"id","token"}] – allegati grandi già caricati (vedi Allegati di grandi dimensioni); solo con ciphertext.
deliver_toFacoltativo (Pro, Pro Plus): fino a 5 indirizzi a cui Kriptano invia subito il link via e-mail. Funziona quando invii il testo in chiaro (secret).
deliver_noteFacoltativo: un breve messaggio al destinatario (fino a 500 caratteri, senza HTML). Non inserire dati riservati – il messaggio non è cifrato.

Per uno zero-knowledge completo, cifra dal tuo lato (sezione successiva) – così il server non vede mai né il testo in chiaro né la chiave.

Generatore di password

GET o POST /password restituisce password, passphrase o PIN casuali. Funziona con tutti i piani: senza chiave API (limitato per indirizzo IP) o con una chiave su Pro e Pro Plus (limite del tuo piano). Nulla viene salvato o registrato; la risposta ha Cache-Control: no-store. Per la massima privacy, genera nel browser dalla pagina Generatore di password.

curl "https://kriptano.com/api/v1/password?length=20&count=3"

curl "https://kriptano.com/api/v1/password?type=passphrase&words=6&separator=-&capitalize=first&wordlist=it&format=text"

Risposta (201):

{
  "type": "password",
  "passwords": ["q7#Vt9…", "…", "…"],
  "password": "q7#Vt9…",
  "length": 20,
  "entropy_bits": 131.1,
  "strength": "very_strong",
  "charset_size": 94
}
CampoDescrizione
typepassword (predefinito), passphrase, pin o pronounceable.
lengthLunghezza: password 4–128 (20), pin 4–12 (6), pronounceable 6–64 (18).
countQuante generarne insieme: 1–100.
lowercase, uppercase, numbers, symbolsSet di caratteri (true/false; tutti attivi per impostazione predefinita). Almeno un carattere di ogni set attivo.
symbol_set, extended_symbols, exclude, exclude_similarIl tuo elenco di simboli, simboli estesi, caratteri da escludere, senza caratteri simili (I l 1 | O 0 o).
min_numbers, min_symbols, start_with_letterNumeri e simboli minimi (1 per impostazione predefinita), primo carattere una lettera.
words, separator, capitalize, include_number, include_symbol, wordlistPassphrase: 3–20 parole, separatore (- . _ space none digit symbol), capitalize (none, first, upper, random), numero e simbolo, elenco di parole en, de, fr, it, es, bcms o sl.
formatjson (predefinito) o text – una password per riga.

Genera e invia con una sola chiamata: "generate" al posto di "secret" in POST /secrets (Pro, Pro Plus). Il server crea la password, la cifra come segreto monouso e restituisce il link e la password (salvo "return_password": false).

curl -X POST https://kriptano.com/api/v1/secrets \
  -H "Authorization: Bearer $KRIPTANO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "generate": { "type": "password", "length": 24 }, "expires": 86400, "views": 1, "deliver_to": ["anna@client.com"] }'

→ { "id": "…", "url": "https://kriptano.com/s/…#…", "password": "…", "status": "active", … }

Limiti senza chiave: 30 richieste al minuto e 1.000 al giorno per indirizzo IP (HTTP 429 se superati). Con una chiave: 60 (Pro) o 300 (Pro Plus) al minuto.

Cifrare dal tuo lato

Formato: AES-256-GCM, chiave da 32 byte, IV da 12 byte, testo cifrato = "v1." + base64url(IV) + "." + base64url(testo cifrato+tag). Il contenuto è un JSON {"v":1,"t":"testo"}. Il token “auth” = base64url(SHA-256(chiave ‖ "kriptano-auth")). Consigliato: il campo “link” = base64url(SHA-256(chiave ‖ "kriptano-link")) – prova del possesso del link; senza di esso una passphrase errata consuma tentativi anche per chi conosce solo l’ID.

// Node.js 18+ / browser (Web Crypto)
const te = new TextEncoder();
const b64u = (b) => Buffer.from(b).toString('base64url');
const raw = crypto.getRandomValues(new Uint8Array(32));          // key – stays with you
const iv  = crypto.getRandomValues(new Uint8Array(12));
const key = await crypto.subtle.importKey('raw', raw, 'AES-GCM', false, ['encrypt']);
const body = te.encode(JSON.stringify({ v: 1, t: 'Password: Gx7!pQ2m' }));
const ct  = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, body));
const auth = b64u(new Uint8Array(await crypto.subtle.digest('SHA-256',
  new Uint8Array([...raw, ...te.encode('kriptano-auth')]))));

const res = await fetch('https://kriptano.com/api/v1/secrets', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.KRIPTANO_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ ciphertext: `v1.${b64u(iv)}.${b64u(ct)}`, auth, expires: 86400, views: 1 })
}).then(r => r.json());

console.log(res.url + '#' + b64u(raw));   // link for the recipient

Con una passphrase aggiuntiva: chiave finale = PBKDF2-SHA256(passphrase, sale = chiave dal link, 600.000 iterazioni, 32 byte); usala per cifrare e calcolare “auth” e aggiungi "passphrase": true, "kdf": 600000 alla richiesta.

Elenco, stato ed eliminazione

GET    https://kriptano.com/api/v1/secrets?status=active&page=1&per_page=25
GET    https://kriptano.com/api/v1/secrets/{id}
DELETE https://kriptano.com/api/v1/secrets/{id}

La risposta contiene solo metadati (stato, numero di aperture, date) – mai il contenuto. Il totale è nell’intestazione X-Total-Count.

<?php
$ch = curl_init( 'https://kriptano.com/api/v1/secrets' );
curl_setopt_array( $ch, [
  CURLOPT_POST           => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [ 'Authorization: Bearer ' . getenv( 'KRIPTANO_KEY' ), 'Content-Type: application/json' ],
  CURLOPT_POSTFIELDS     => json_encode( [ 'secret' => 'PIN: 4821', 'expires' => 3600 ] ),
] );
$res = json_decode( curl_exec( $ch ), true );
echo $res['url'];

Allegati di grandi dimensioni (fino a 10 GB)

Gli allegati più piccoli possono andare nel campo files (base64, fino a 25 MB, cifrati dal server). I file più grandi vengono cifrati dal tuo lato a blocchi e inviati direttamente all’archivio tramite link firmati – il server di Kriptano non vede mai né il contenuto né la chiave. Se la connessione cade, richiedi nuovi link solo per i blocchi mancanti.

POST https://kriptano.com/kx-api/uploads            (Authorization: Bearer kx_live_…)
{ "files": [ { "size": 734003200 } ] }
→ { "chunk": 16777216, "tag": 16, "ttl": 10800,
    "uploads": [ { "id": "…", "token": "…", "parts": 44, "urls": [ "https://…", … ] } ] }

PUT  urls[n-1]          ← encrypted chunk n (chunk + 16 B; the last one may be shorter)
POST https://kriptano.com/kx-api/uploads/{id}/urls     { "token": "…", "parts": [7, 8] }   (new links)
POST https://kriptano.com/kx-api/uploads/{id}/complete { "token": "…" }

POST https://kriptano.com/api/v1/secrets
{ "ciphertext": "v1.…", "auth": "…", "uploads": [ { "id": "…", "token": "…" } ] }

Formato: ogni blocco è AES-256-GCM con la chiave del file (256 bit), nonce = 3 byte nulli ‖ indice del blocco (64 bit, big-endian) ‖ 1 byte (1 per l’ultimo blocco), AAD = “kriptano-file-v1”. La chiave e i dati del file (id, nome, tipo, dimensione, dimensione del blocco) vanno nel contenuto cifrato del segreto come {"f":[{"v":2,"id","n","m","s","k","c"}]}. Implementazione di riferimento: assets/js/files.js.

Invio via e-mail

Con deliver_to Kriptano invia direttamente il link al destinatario – dal tuo dominio e-mail o tramite il tuo server SMTP (Pro Plus), altrimenti da un indirizzo Kriptano. La chiave è nel link, quindi l’e-mail parte solo se il server la conosce (testo in chiaro); per i segreti cifrati dal tuo lato, invia tu il link. La risposta contiene delivered e, se l’invio non riesce, delivery_error – il segreto viene creato comunque.

POST https://kriptano.com/api/v1/secrets
{ "secret": "VPN: user / password", "expires": 86400,
  "deliver_to": [ "anna@client.com" ], "deliver_note": "Access for the new office." }
→ { "id": "…", "url": "https://…/s/…#…", "delivered": true, … }

POST https://kriptano.com/api/v1/requests
{ "label": "FTP access", "public_key": "…", "deliver_to": [ "mark@client.com" ] }

Richieste di segreti

Una richiesta cifra le risposte con la tua chiave pubblica RSA. La coppia di chiavi la generi tu; la chiave privata resta a te e la usi per decifrare le risposte.

POST https://kriptano.com/api/v1/requests
{ "label": "FTP access", "instructions": "Please send the host, username and password.",
  "public_key": "<SPKI RSA-OAEP 2048, base64url>", "expires_days": 14, "max_responses": 1 }

GET  https://kriptano.com/api/v1/requests/{id}/responses
→ [ { "id": "…", "ciphertext": "r1.<RSA-OAEP(AES key)>.<iv>.<AES-GCM ciphertext>", "created_at": "…" } ]

Registro di audit

Gli eventi del tuo account (Pro, Pro Plus) per un SIEM o un archivio: periodo (from, to), tipo, fino a 500 per pagina. Il registro non contiene mai il contenuto dei segreti, le chiavi o i link; il paese proviene da un database di geolocalizzazione locale. Gli stessi dati del CSV: Il mio account → Registro di audit → Esporta CSV.

GET https://kriptano.com/api/v1/log?from=2026-11-01&to=2026-11-30&type=secret_viewed&page=1&per_page=100
→ [ { "id": 812, "time": "2026-11-08T09:14:02+00:00", "type": "secret_viewed", "event": "Secret opened",
      "user": null, "country": "HR", "object_id": "…", "message": "…" } ]      (X-Total-Count: 37)

Webhook

Pro e Pro Plus: aggiungi un URL HTTPS in Il mio account → Webhook e scegli gli eventi. Kriptano invia un POST JSON subito dopo l’evento; il contenuto del segreto, la chiave e il link non sono mai inclusi (il server non li possiede).

Eventi: secret.created, secret.viewed, secret.locked, secret.deleted, secret.expired, request.created, request.answered, team.member_joined, team.member_removed, ping.

POST https://example.com/hooks/kriptano
Content-Type: application/json; charset=utf-8
Kriptano-Event: secret.viewed
Kriptano-Delivery: evt_3kT9…
Kriptano-Signature: t=1762770000,v1=5f2c…e91a

{ "id": "evt_3kT9…", "type": "secret.viewed", "created": "2026-11-10T09:14:02Z",
  "data": { "secret": { "id": "Qm7x…", "label": "Hosting – client Smith", "status": "burned",
            "views": 1, "max_views": 1, "has_passphrase": true, "files": false, "source": "web",
            "created_at": "…", "expires_at": "…", "viewed_at": "…" },
            "viewer": { "country": "HR" } } }

Verifica la firma: HMAC-SHA256 di “t.body” con il segreto whsec_… deve essere uguale a v1, e t non deve essere più vecchio di 5 minuti. Usa il corpo grezzo della richiesta (prima del parsing JSON).

// Node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {           // header = req.headers['kriptano-signature']
  const p = Object.fromEntries(header.split(',').map(s => s.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const mac = crypto.createHmac('sha256', secret).update(p.t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(p.v1));
}

# PHP
$p = []; parse_str(str_replace(',', '&', $_SERVER['HTTP_KRIPTANO_SIGNATURE']), $p);
$ok = abs(time() - (int) $p['t']) <= 300
   && hash_equals(hash_hmac('sha256', $p['t'] . '.' . file_get_contents('php://input'), $secret), $p['v1']);

Rispondi con uno stato 2xx entro 10 secondi. In caso di errori o timeout riproviamo dopo 1 min, 5 min, 30 min, 2 h, 6 h e 12 h; lo stato 410 interrompe le consegne. Dopo 50 errori consecutivi il webhook viene disattivato. Lo stesso evento può arrivare due volte – usa il campo id (Kriptano-Delivery) per eliminare i duplicati.

Errori

HTTPDescrizione
400Dati non validi (messaggio nel campo "message").
401Chiave API mancante o non valida.
402Il piano non include l’API.
403Limite del piano superato (durata, numero di aperture, allegati).
404 / 410Il segreto non esiste, è stato aperto o è scaduto.
413Il contenuto è troppo grande.
429Troppe richieste o quota mensile esaurita.

Integrazioni

Quando usare l’API REST

L’integrazione è pensata per i team che inviano password dai propri sistemi: un helpdesk che invia una password temporanea, un CRM che consegna le credenziali a un nuovo cliente o uno script che invia un link monouso dopo aver attivato un server.

Puoi cifrare tu il segreto (Web Crypto, AES-256-GCM – vedi la documentazione MDN) e inviare solo il testo cifrato, oppure inviare il testo in chiaro via HTTPS: il server lo cifra nello stesso formato e non conserva mai la chiave.

Crea una chiave API in Il mio account con i piani Pro e Pro Plus (confronta i piani). I segreti creati vengono conteggiati nella quota mensile del piano.

La risposta contiene il link con la chiave dopo il #, la scadenza e il numero di aperture rimaste. Passi il link all’utente come qualsiasi altro – via e-mail, messaggio o nell’interfaccia della tua app. Quando l’utente apre il segreto, il testo cifrato viene eliminato e il tuo elenco di segreti lo mostra come aperto.

Una richiesta di segreto funziona al contrario: il tuo sistema crea un link in cui il cliente inserisce i dati, e la risposta viene cifrata con una chiave pubblica che hai generato tu. Così le risposte restano illeggibili per tutti tranne che per te.

  1. API REST di Kriptano – segreto, cifratura, link e apertura unicaInserisci il segreto
  2. Cifrato nel browserCifrato nel browser
  3. Invia il linkInvia il link
  4. Si apre una volta, poi sparisceSi apre una volta, poi sparisce