API та клієнтські бібліотеки

Усе, що вебзастосунок робить із таємницею, можна зробити через HTTPS із JSON. Типовий підхід — сценарій або конвеєр, який створює таємницю й передає посилання людині, тож облікові дані ніколи не осідають у журналі, тікеті чи історії чату.

Повний довідник кінцевих точок зі схемами запитів і відповідей та консоллю для випробування розміщено на api.onetimesecret.com. Ця сторінка описує те, що вам потрібно знати перед тим, як його відкрити.

Базова URL-адреса

Запити надсилаються до регіону, у якому розміщено ваш обліковий запис. Кожен регіон — окреме розгортання, і між ними нічого не реплікується.

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

`REGION`	Хост
`ca`	`ca.onetimesecret.com`
`eu`	`eu.onetimesecret.com`
`nz`	`nz.onetimesecret.com`
`uk`	`uk.onetimesecret.com`
`us`	`us.onetimesecret.com`

Хост onetimesecret.com без префікса досі відповідає на запити API та маршрутизує їх до активного регіону, але вказуйте регіон явно, щоб ваша інтеграція продовжувала працювати, якщо цей резервний варіант буде вилучено. Про те, що кожен регіон означає для ваших даних, див. Де зберігаються ваші дані.

На користувацькому домені API доступний за тим самим шляхом на вашому домені, а створені ним посилання використовують цей домен:

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

Самостійно розгорнутий екземпляр надає той самий API на тому хості, на якому ви його запускаєте.

Автентифікація

Використовуйте HTTP Basic-автентифікацію. Ім'я користувача — електронна адреса вашого облікового запису; пароль — токен API з налаштувань вашого облікового запису.

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

Створення та розкриття таємниць також працює без автентифікації з обмеженнями анонімного користувача: коротший максимальний термін дії, менший розмір таємниці та відсутність списку квитанцій. Автентифіковані запити отримують ліміти вашого тарифного плану та з'являються у ваших квитанціях.

Швидкий старт

Створіть таємницю, яка діятиме одну годину:

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

Відповідь містить два записи. record.secret.identifier — це ключ, яким ви ділитеся, у вигляді https://eu.onetimesecret.com/secret/IDENTIFIER. record.receipt.identifier — ваш: він показує, чи було переглянуто таємницю, і дозволяє знищити її достроково. Ніколи не надсилайте ключ квитанції одержувачу.

Додайте "passphrase": "..." до об'єкта secret, щоб вимагати парольну фразу під час перегляду. Парольна фраза — це перевірка доступу, а не ключ шифрування: сервіс зберігає лише її односторонній хеш і перевіряє її перед розшифруванням значення. Втрачену парольну фразу неможливо відновити, тому таку таємницю не можна ні розкрити, ні знищити; її буде видалено, коли спливе термін дії.

Розкрийте таємницю (розкриття її витрачає):

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

Знищіть таємницю до того, як її хтось перегляне, використовуючи ключ квитанції:

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

Версії API

v2 — поточний публічний API: JSON на вході й виході, квитанції, кінцеві точки статусу та знищення. Будуйте інтеграції на ньому.
v1 — початковий API з кодуванням форми (POST /api/v1/share). Він досі працює, і більшість бібліотек спільноти використовують саме його, але нові інтеграції мають використовувати v2.

Обидва задокументовано на api.onetimesecret.com.

Клієнтські бібліотеки

Клієнтські бібліотекиОфіційний SDK і бібліотеки спільноти з примітками про те, які з них підтримують API v2, регіони та користувацькі домени.

Повний довідник APIКожна кінцева точка v1 і v2, схеми запитів і відповідей та консоль для випробування викликів із вашим обліковим записом.

Пов'язані сторінки

Де зберігаються ваші дані: вибір регіону та що залишається всередині нього.
Користувацькі домени: таємні посилання та доступ до API на вашому власному домені.
Самостійне розгортання: запуск API на власній інфраструктурі.
Вступ для розробників: локальний запуск застосунку та участь у розробці.