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 на собствена инфраструктура.
Въведение за разработчици: изпълнявайте приложението локално и допринасяйте.