コンテンツにスキップ
Onetime Secret DocsOnetime Secret DocsOnetime Secret - Docs

APIとクライアントライブラリ

ウェブアプリがシークレットに対して行えることはすべて、HTTPS経由のJSONで実行できます。よくあるパターンは、スクリプトやパイプラインがシークレットを作成してリンクを人に渡すというもので、これにより資格情報がログ、チケット、チャット履歴に残ることがなくなります。

リクエストとレスポンスのスキーマ、および試用コンソールを含む完全なエンドポイントリファレンスは api.onetimesecret.com にあります。このページでは、それを開く前に必要となる事項を説明します。

ベースURL

「ベースURL」セクション

リクエストは、アカウントを保持しているリージョンに送信します。各リージョンは別々のデプロイメントであり、リージョン間で複製されるものは何もありません。

https://REGION.onetimesecret.com/api/v2
REGIONホスト
caca.onetimesecret.com
eueu.onetimesecret.com
nznz.onetimesecret.com
ukuk.onetimesecret.com
usus.onetimesecret.com

リージョンなしの onetimesecret.com ホストも引き続きAPIリクエストに応答し、有効なリージョンにルーティングしますが、このフォールバックが廃止されても連携が機能し続けるように、リージョンを明示的に固定してください。各リージョンがデータにとって何を意味するかは、データの保存場所をご覧ください。

カスタムドメインでは、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

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

クイックスタート

「クイックスタート」セクション

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

ターミナルウィンドウ
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": "..." を追加します。パスフレーズはアクセスの確認手段であり、暗号化キーではありません。サービスはパスフレーズの一方向ハッシュのみを保存し、値を復号する前にそれを照合します。紛失したパスフレーズは復元できないため、そのシークレットは閲覧も削除もできなくなり、有効期限が切れると削除されます。

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

ターミナルウィンドウ
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バージョン

「APIバージョン」セクション
  • v2 は現行の公開APIです。入出力ともJSONで、受信確認、ステータス、削除のエンドポイントがあります。これを基に構築してください。
  • v1 は元のフォームエンコード形式のAPIです（POST /api/v1/share）。引き続き機能し、コミュニティライブラリの多くはこちらを使用していますが、新しい連携にはv2を使用してください。

どちらも api.onetimesecret.com でドキュメント化されています。

クライアントライブラリ

「クライアントライブラリ」セクション
クライアントライブラリ公式SDKとコミュニティライブラリ。API v2、リージョン、カスタムドメインへの対応状況の注記付きです。
完全なAPIリファレンスv1とv2のすべてのエンドポイント、リクエストとレスポンスのスキーマ、そしてアカウントに対して呼び出しを試せるコンソールです。

関連ページ

「関連ページ」セクション