# 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/)をご覧ください。

[カスタムドメイン](/ja/custom-domains/)では、APIはそのドメイン上の同じパスにあり、APIが作成するリンクにはそのドメインが使われます。

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

[セルフホスト](/ja/self-hosting/)のインスタンスは、実行しているホスト上で同じAPIを公開します。

## 認証

HTTP Basic認証を使用します。ユーザー名はアカウントのメールアドレス、パスワードはアカウント設定で取得できるAPIトークンです。

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

シークレットの作成と閲覧は認証なしでも機能しますが、匿名ユーザーの制限が適用されます。最大有効期間が短く、シークレットのサイズが小さく、受信確認の一覧がありません。認証済みのリクエストにはプランの制限が適用され、[受信確認](/en/share/your-receipt/)に表示されます。

## クイックスタート

1時間有効なシークレットを作成します。

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

レスポンスには2つのレコードが含まれます。`record.secret.identifier` は共有するキーで、`https://eu.onetimesecret.com/secret/IDENTIFIER` の形で渡します。`record.receipt.identifier` は自分用のキーで、シークレットが閲覧されたかどうかを示し、早期に削除することを可能にします。受信確認のキーは決して受信者に送らないでください。

閲覧時にパスフレーズを要求するには、`secret` オブジェクトに `"passphrase": "..."` を追加します。パスフレーズはアクセスの確認手段であり、暗号化キーではありません。サービスはパスフレーズの一方向ハッシュのみを保存し、値を復号する前にそれを照合します。紛失したパスフレーズは復元できないため、そのシークレットは閲覧も削除もできなくなり、有効期限が切れると削除されます。

シークレットを閲覧します。これによりシークレットは消費されます。

```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) でドキュメント化されています。

## クライアントライブラリ

[クライアントライブラリ](/ja/api/client-libraries/)公式SDKとコミュニティライブラリ。API v2、リージョン、カスタムドメインへの対応状況の注記付きです。

[完全なAPIリファレンス](https://api.onetimesecret.com)v1とv2のすべてのエンドポイント、リクエストとレスポンスのスキーマ、そしてアカウントに対して呼び出しを試せるコンソールです。

## 関連ページ

* [データの保存場所](/en/security/where-your-data-lives/)：リージョンの選び方と、リージョン内に留まるもの。
* [カスタムドメイン](/ja/custom-domains/)：独自ドメインでのシークレットリンクとAPIアクセス。
* [セルフホスティング](/ja/self-hosting/)：独自のインフラストラクチャでAPIを実行する。
* [開発者向けオンランプ](/en/contribute/developer-on-ramp/)：アプリケーションをローカルで実行し、貢献する。