API e librerie client

Tutto ciò che l'app web fa con un segreto può essere fatto via HTTPS con JSON. Lo schema più comune è uno script o una pipeline che crea un segreto e consegna il link a una persona, così la credenziale non finisce mai in un log, in un ticket o nella cronologia di una chat.

Il riferimento completo degli endpoint, con gli schemi di richiesta e risposta e una console di prova, si trova su api.onetimesecret.com. Questa pagina copre ciò che ti serve prima di aprirlo.

URL di base

Le richieste vanno alla regione che ospita il tuo account. Ogni regione è un deployment separato e nulla viene replicato tra le regioni.

https://REGION.onetimesecret.com/api/v2

`REGION`	Host
`ca`	`ca.onetimesecret.com`
`eu`	`eu.onetimesecret.com`
`nz`	`nz.onetimesecret.com`
`uk`	`uk.onetimesecret.com`
`us`	`us.onetimesecret.com`

L'host semplice onetimesecret.com risponde ancora alle richieste API e le instrada a una regione attiva, ma indica esplicitamente una regione, così la tua integrazione continuerà a funzionare se quel fallback verrà ritirato. Vedi Dove risiedono i tuoi dati per sapere cosa comporta ogni regione per i tuoi dati.

Su un dominio personalizzato, l'API si trova allo stesso percorso sul tuo dominio, e i link che crea usano quel dominio:

https://secrets.example.com/api/v2

Un'istanza self-hosted espone la stessa API su qualunque host tu la esegua.

Autenticazione

Usa l'autenticazione HTTP Basic. Il nome utente è l'email del tuo account; la password è il token API che trovi nelle impostazioni dell'account.

curl -u 'you@example.com:APITOKEN' https://eu.onetimesecret.com/api/v2/status

Creare e rivelare segreti funziona anche senza autenticazione, con i limiti di un utente anonimo: durata massima più breve, dimensione del segreto più piccola e nessun elenco delle ricevute. Le richieste autenticate ottengono i limiti del tuo piano e compaiono nelle tue ricevute.

Guida rapida

Crea un segreto che dura un'ora:

curl -u 'you@example.com:APITOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"secret": {"secret": "the password is hunter2", "ttl": 3600}}' \
  https://eu.onetimesecret.com/api/v2/secret/conceal

La risposta contiene due record. record.secret.identifier è la chiave che condividi, nella forma https://eu.onetimesecret.com/secret/IDENTIFIER. record.receipt.identifier è la tua chiave: mostra se il segreto è stato visualizzato e ti permette di distruggerlo in anticipo. Non inviare mai la chiave della ricevuta al destinatario.

Aggiungi "passphrase": "..." all'oggetto secret per richiedere una frase di sicurezza alla visualizzazione. La frase di sicurezza è un controllo di accesso, non la chiave di crittografia: il servizio ne memorizza solo un hash unidirezionale e la controlla prima di decrittografare il valore. Una frase di sicurezza persa non è recuperabile, quindi il segreto non può più essere né rivelato né distrutto; viene eliminato alla scadenza.

Rivela un segreto, consumandolo:

curl -X POST -H 'Content-Type: application/json' -d '{}' \
  https://eu.onetimesecret.com/api/v2/secret/IDENTIFIER/reveal

Distruggi un segreto prima che qualcuno lo visualizzi, usando la chiave della ricevuta:

curl -u 'you@example.com:APITOKEN' -X POST \
  https://eu.onetimesecret.com/api/v2/receipt/RECEIPT_IDENTIFIER/burn

Versioni dell'API

v2 è l'API pubblica attuale: JSON in ingresso e in uscita, ricevute, endpoint di stato e di distruzione. Usa questa per le tue integrazioni.
v1 è l'API originale con codifica form (POST /api/v1/share). Funziona ancora, e la maggior parte delle librerie della community la usa, ma le nuove integrazioni dovrebbero usare la v2.

Entrambe sono documentate su api.onetimesecret.com.

Librerie client

Librerie clientL'SDK ufficiale e le librerie della community, con note su quali supportano l'API v2, le regioni e i domini personalizzati.

Riferimento API completoOgni endpoint della v1 e della v2, gli schemi di richiesta e risposta e una console per provare le chiamate sul tuo account.

Pagine correlate

Dove risiedono i tuoi dati: scegliere una regione e cosa resta al suo interno.
Domini personalizzati: link segreti e accesso API sul tuo dominio.
Self-hosting: esegui l'API sulla tua infrastruttura.
Percorso per sviluppatori: esegui l'applicazione in locale e contribuisci.