# API и клиентски библиотеки

> Създавайте, извличайте и изтривайте тайни от собствения си код. Регионални базови URL адреси, удостоверяване, бърз старт с curl и официалните клиентски библиотеки и тези от общността.

Всичко, което уеб приложението прави с една тайна, може да се направи през HTTPS с JSON. Обичайният модел е скрипт или конвейер, който създава тайна и предава връзката на човек, така че идентификационните данни никога не остават в журнал, тикет или история на чат.

Пълната справка за крайните точки, със схеми на заявките и отговорите и конзола за изпробване, се намира на **[api.onetimesecret.com](https://api.onetimesecret.com)**. Тази страница обхваща това, което ви е необходимо, преди да я отворите.

## Базов URL

Заявките отиват към региона, в който е акаунтът ви. Всеки регион е отделно разгръщане и нищо не се реплицира между тях.

```plaintext
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 заявки и маршрутизира към активен регион, но задайте региона явно, за да продължи интеграцията ви да работи, ако този резервен вариант бъде премахнат. Вижте [Къде се намират данните ви](/en/security/where-your-data-lives/) за това какво означава всеки регион за данните ви.

На [потребителски домейн](/bg/custom-domains/) API е на същия път на вашия домейн, а връзките, които създава, използват този домейн:

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

[Самостоятелно хостван](/bg/self-hosting/) екземпляр предоставя същия API на хоста, на който го изпълнявате.

## Удостоверяване

Използвайте HTTP Basic удостоверяване. Потребителското име е имейлът на акаунта ви; паролата е API токенът от настройките на акаунта ви.

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

Създаването и разкриването на тайни работи и без удостоверяване, с ограниченията на анонимен потребител: по-кратък максимален срок на валидност, по-малък размер на тайната и без списък с разписки. Удостоверените заявки получават лимитите на плана ви и се показват в [разписките](/en/share/your-receipt/) ви.

## Бърз старт

Създайте тайна, валидна един час:

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

Отговорът съдържа два записа. `record.secret.identifier` е ключът, който споделяте, като `https://eu.onetimesecret.com/secret/IDENTIFIER`. `record.receipt.identifier` е ваш: той показва дали тайната е била прегледана и ви позволява да я изтриете предсрочно. Никога не изпращайте ключа на разписката на получателя.

Добавете `"passphrase": "..."` към обекта `secret`, за да изисквате ключова фраза при преглеждане. Ключовата фраза е проверка за достъп, а не ключът за криптиране: услугата съхранява само еднопосочен хеш от нея и я проверява, преди да декриптира стойността. Изгубена ключова фраза не може да бъде възстановена, така че тогава тайната не може нито да бъде разкрита, нито изтрита; тя се изтрива, когато срокът ѝ на валидност изтече.

Разкрийте тайна, което я консумира:

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

Изтрийте тайна, преди някой да я е прегледал, с помощта на ключа на разписката:

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

## Клиентски библиотеки

[Клиентски библиотеки](/bg/api/client-libraries/)Официалният SDK и библиотеките от общността, с бележки кои поддържат API v2, региони и потребителски домейни.

[Пълна справка за API](https://api.onetimesecret.com)Всяка крайна точка за v1 и v2, схеми на заявките и отговорите и конзола за изпробване на извиквания към вашия акаунт.

## Свързани теми

* [Къде се намират данните ви](/en/security/where-your-data-lives/): избор на регион и какво остава в него.
* [Потребителски домейни](/bg/custom-domains/): тайни връзки и API достъп на собствен домейн.
* [Самостоятелно хостване](/bg/self-hosting/): изпълнявайте API на собствена инфраструктура.
* [Въведение за разработчици](/en/contribute/developer-on-ramp/): изпълнявайте приложението локално и допринасяйте.