# API e librerie client

> Crea, recupera e distruggi segreti dal tuo codice. URL di base regionali, autenticazione, una guida rapida con curl e le librerie client ufficiali e della community.

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](https://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.

```plaintext
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](/en/security/where-your-data-lives/) per sapere cosa comporta ogni regione per i tuoi dati.

Su un [dominio personalizzato](/it/custom-domains/), l'API si trova allo stesso percorso sul tuo dominio, e i link che crea usano quel dominio:

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

Un'istanza [self-hosted](/it/self-hosting/) 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.

```bash
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](/en/share/your-receipt/).

## Guida rapida

Crea un segreto che dura un'ora:

```bash
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:

```bash
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:

```bash
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](https://api.onetimesecret.com).

## Librerie client

[Librerie client](/it/api/client-libraries/)L'SDK ufficiale e le librerie della community, con note su quali supportano l'API v2, le regioni e i domini personalizzati.

[Riferimento API completo](https://api.onetimesecret.com)Ogni 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](/en/security/where-your-data-lives/): scegliere una regione e cosa resta al suo interno.
* [Domini personalizzati](/it/custom-domains/): link segreti e accesso API sul tuo dominio.
* [Self-hosting](/it/self-hosting/): esegui l'API sulla tua infrastruttura.
* [Percorso per sviluppatori](/en/contribute/developer-on-ramp/): esegui l'applicazione in locale e contribuisci.