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.
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"
}
| Campo | Descrizione |
|---|---|
secret | Testo segreto (fino a ~90.000 caratteri). |
files | Facoltativo: [{"name","type","data"(base64)}] – allegati, se il piano li consente. |
expires | Durata in secondi: 3600, 86400, 259200, 604800, 1209600, 2592000, 7776000, 15552000, 31536000 (entro il limite del piano). |
views | Numero di aperture (predefinito 1). |
passphrase | Facoltativa: passphrase aggiuntiva che il destinatario deve inserire. |
label | Etichetta interna (visibile solo a te; non inserire dati segreti). |
notify | true = notifica via e-mail all’apertura del segreto. |
uploads | Facoltativo: [{"id","token"}] – allegati grandi già caricati (vedi Allegati di grandi dimensioni); solo con ciphertext. |
deliver_to | Facoltativo (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_note | Facoltativo: 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
}
| Campo | Descrizione |
|---|---|
type | password (predefinito), passphrase, pin o pronounceable. |
length | Lunghezza: password 4–128 (20), pin 4–12 (6), pronounceable 6–64 (18). |
count | Quante generarne insieme: 1–100. |
lowercase, uppercase, numbers, symbols | Set di caratteri (true/false; tutti attivi per impostazione predefinita). Almeno un carattere di ogni set attivo. |
symbol_set, extended_symbols, exclude, exclude_similar | Il tuo elenco di simboli, simboli estesi, caratteri da escludere, senza caratteri simili (I l 1 | O 0 o). |
min_numbers, min_symbols, start_with_letter | Numeri e simboli minimi (1 per impostazione predefinita), primo carattere una lettera. |
words, separator, capitalize, include_number, include_symbol, wordlist | Passphrase: 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. |
format | json (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
| HTTP | Descrizione |
|---|---|
| 400 | Dati non validi (messaggio nel campo "message"). |
| 401 | Chiave API mancante o non valida. |
| 402 | Il piano non include l’API. |
| 403 | Limite del piano superato (durata, numero di aperture, allegati). |
| 404 / 410 | Il segreto non esiste, è stato aperto o è scaduto. |
| 413 | Il contenuto è troppo grande. |
| 429 | Troppe 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.
Inserisci il segreto
Cifrato nel browser
Invia il link
Si apre una volta, poi sparisce