# API i biblioteki klienckie

> Twórz, pobieraj i niszcz sekrety z własnego kodu. Regionalne bazowe adresy URL, uwierzytelnianie, szybki start z curl oraz oficjalne i społecznościowe 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](https://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.

```plaintext
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](/en/security/where-your-data-lives/).

W [domenie niestandardowej](/pl/custom-domains/) API jest dostępne pod tą samą ścieżką w Twojej domenie, a tworzone przez nie linki używają tej domeny:

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

Instancja [self-hosted](/pl/self-hosting/) 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.

```bash
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](/en/share/your-receipt/).

## Szybki start

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

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

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:

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

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

## Biblioteki klienckie

[Biblioteki klienckie](/pl/api/client-libraries/)Oficjalny SDK i biblioteki społeczności, z informacją, które obsługują API v2, regiony i domeny niestandardowe.

[Pełna dokumentacja API](https://api.onetimesecret.com)Każ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](/en/security/where-your-data-lives/): wybór regionu i to, co w nim pozostaje.
* [Domeny niestandardowe](/pl/custom-domains/): linki do sekretów i dostęp do API w Twojej własnej domenie.
* [Self-hosting](/pl/self-hosting/): uruchom API na własnej infrastrukturze.
* [Wprowadzenie dla deweloperów](/en/contribute/developer-on-ramp/): uruchom aplikację lokalnie i współtwórz ją.