API i biblioteki klienckie

Wszystko, co aplikacja internetowa robi z sekretem, można wykonać przez HTTPS z użyciem JSON. Typowy wzorzec to skrypt lub pipeline, który tworzy sekret i przekazuje link osobie, dzięki czemu dane uwierzytelniające nigdy nie trafiają do logu, zgłoszenia ani historii czatu.

Pełna dokumentacja punktów końcowych, ze schematami żądań i odpowiedzi oraz konsolą do testowania, znajduje się pod adresem api.onetimesecret.com. Ta strona opisuje to, co musisz wiedzieć, zanim ją otworzysz.

Bazowy URL

Żądania trafiają do regionu, w którym znajduje się Twoje konto. Każdy region jest osobnym wdrożeniem i nic nie jest między nimi replikowane.

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`

Sam host onetimesecret.com nadal odpowiada na żądania API i kieruje je do aktywnego regionu, ale wskaż region wprost, aby Twoja integracja działała nadal, jeśli ten mechanizm zapasowy zostanie wycofany. Co każdy region oznacza dla Twoich danych, opisuje artykuł Gdzie znajdują się Twoje dane.

W domenie niestandardowej API jest dostępne pod tą samą ścieżką w Twojej domenie, a tworzone przez nie linki używają tej domeny:

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

Instancja self-hosted udostępnia to samo API na dowolnym hoście, na którym ją uruchamiasz.

Uwierzytelnianie

Użyj uwierzytelniania HTTP Basic. Nazwą użytkownika jest adres e-mail Twojego konta; hasłem jest token API z ustawień konta.

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

Tworzenie i wyświetlanie sekretów działa także bez uwierzytelniania, z limitami użytkownika anonimowego: krótszym maksymalnym czasem ważności, mniejszym rozmiarem sekretu i bez listy potwierdzeń. Uwierzytelnione żądania otrzymują limity Twojego planu i pojawiają się w Twoich potwierdzeniach.

Szybki start

Utwórz sekret, który istnieje przez jedną godzinę:

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

Odpowiedź zawiera dwa rekordy. record.secret.identifier to klucz, który udostępniasz, w postaci https://eu.onetimesecret.com/secret/IDENTIFIER. record.receipt.identifier jest dla Ciebie: pokazuje, czy sekret został wyświetlony, i pozwala zniszczyć go wcześniej. Nigdy nie wysyłaj klucza potwierdzenia odbiorcy.

Dodaj "passphrase": "..." do obiektu secret, aby wymagać frazy dostępowej przy wyświetlaniu. Fraza dostępowa jest kontrolą dostępu, a nie kluczem szyfrującym: usługa przechowuje tylko jej jednokierunkowy skrót i sprawdza ją przed odszyfrowaniem wartości. Utraconej frazy dostępowej nie da się odzyskać, więc takiego sekretu nie można wtedy ani wyświetlić, ani zniszczyć; jest on usuwany, gdy wygaśnie.

Wyświetl sekret, co go zużywa:

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

Zniszcz sekret, zanim ktokolwiek go wyświetli, używając klucza potwierdzenia:

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

Wersje API

v2 to bieżące publiczne API: JSON na wejściu i wyjściu, potwierdzenia, punkty końcowe statusu i niszczenia. Buduj na tej wersji.
v1 to pierwotne API kodowane formularzowo (POST /api/v1/share). Nadal działa i korzysta z niego większość bibliotek społeczności, ale nowe integracje powinny używać v2.

Obie wersje są udokumentowane pod adresem api.onetimesecret.com.

Biblioteki klienckie

Biblioteki klienckieOficjalny SDK i biblioteki społeczności, z informacją, które obsługują API v2, regiony i domeny niestandardowe.

Pełna dokumentacja APIKażdy punkt końcowy v1 i v2, schematy żądań i odpowiedzi oraz konsola do testowania wywołań na Twoim koncie.

Powiązane

Gdzie znajdują się Twoje dane: wybór regionu i to, co w nim pozostaje.
Domeny niestandardowe: linki do sekretów i dostęp do API w Twojej własnej domenie.
Self-hosting: uruchom API na własnej infrastrukturze.
Wprowadzenie dla deweloperów: uruchom aplikację lokalnie i współtwórz ją.