API och klientbibliotek

Allt som webbappen gör med en hemlighet kan göras över HTTPS med JSON. Det vanliga mönstret är ett skript eller en pipeline som skapar en hemlighet och lämnar över länken till en person, så att inloggningsuppgiften aldrig hamnar i en logg, ett ärende eller en chatthistorik.

Den fullständiga slutpunktsreferensen, med scheman för begäran och svar och en konsol där du kan testa anrop, finns på api.onetimesecret.com. Den här sidan beskriver vad du behöver innan du öppnar den.

Bas-URL

Begäranden går till den region som har ditt konto. Varje region är en separat driftsättning och ingenting replikeras mellan dem.

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

`REGION`	Värd
`ca`	`ca.onetimesecret.com`
`eu`	`eu.onetimesecret.com`
`nz`	`nz.onetimesecret.com`
`uk`	`uk.onetimesecret.com`
`us`	`us.onetimesecret.com`

Värden onetimesecret.com utan regionprefix svarar fortfarande på API-begäranden och dirigerar till en aktiv region, men ange en region uttryckligen så att din integration fortsätter att fungera om den reservlösningen tas bort. Se Var din data finns för vad varje region innebär för din data.

På en anpassad domän finns API:et på samma sökväg på din domän, och länkarna det skapar använder den domänen:

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

En självhostad instans exponerar samma API på den värd du kör den på.

Autentisering

Använd HTTP Basic-autentisering. Användarnamnet är ditt kontos e-postadress; lösenordet är API-nyckeln från dina kontoinställningar.

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

Att skapa och visa hemligheter fungerar också utan autentisering, med en anonym användares begränsningar: kortare maximal livslängd, mindre hemlighetsstorlek och ingen kvittolista. Autentiserade begäranden får din plans gränser och visas bland dina kvitton.

Snabbstart

Skapa en hemlighet som gäller i en timme:

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

Svaret innehåller två poster. record.secret.identifier är nyckeln du delar, som https://eu.onetimesecret.com/secret/IDENTIFIER. record.receipt.identifier är din: den visar om hemligheten har visats och låter dig bränna den i förtid. Skicka aldrig kvittonyckeln till mottagaren.

Lägg till "passphrase": "..." i objektet secret för att kräva en lösenfras vid visning. Lösenfrasen är en åtkomstkontroll, inte krypteringsnyckeln: tjänsten lagrar bara en envägshash av den och kontrollerar den innan värdet dekrypteras. En förlorad lösenfras kan inte återställas, och då går hemligheten varken att visa eller bränna; den raderas när den går ut.

Visa en hemlighet, vilket förbrukar den:

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

Bränn en hemlighet innan någon har öppnat den, med hjälp av kvittonyckeln:

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

API-versioner

v2 är det aktuella publika API:et: JSON in och ut, kvitton, status- och bränningsslutpunkter. Bygg på det här.
v1 är det ursprungliga formulärkodade API:et (POST /api/v1/share). Det fungerar fortfarande, och de flesta communitybibliotek använder det, men nya integrationer bör använda v2.

Båda dokumenteras på api.onetimesecret.com.

Klientbibliotek

KlientbibliotekDen officiella SDK:n och communitybiblioteken, med noteringar om vilka som stöder API v2, regioner och anpassade domäner.

Fullständig API-referensVarje slutpunkt för v1 och v2, scheman för begäran och svar, och en konsol där du kan testa anrop mot ditt konto.

Relaterat

Var din data finns: att välja en region, och vad som stannar inom den.
Anpassade domäner: hemliga länkar och API-åtkomst på din egen domän.
Självhosting: kör API:et på din egen infrastruktur.
Introduktion för utvecklare: kör applikationen lokalt och bidra.