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가 해당 도메인의 같은 경로에 있으며, 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는 본인용 키로, 비밀 메시지가 열람되었는지 보여 주고 미리 소각할 수 있게 합니다. 수신확인 키는 절대 수신자에게 보내지 마세요.

열람 시 접근 문구를 요구하려면 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 버전

• v2는 현재 공개 API입니다. JSON 입출력, 수신확인, 상태 및 소각 엔드포인트를 제공합니다. 이 버전을 기반으로 개발하세요.
• v1은 원래의 폼 인코딩 API(POST /api/v1/share)입니다. 여전히 작동하며 대부분의 커뮤니티 라이브러리가 사용하지만, 새 통합은 v2를 사용해야 합니다.

두 버전 모두 api.onetimesecret.com에 문서화되어 있습니다.

클라이언트 라이브러리

클라이언트 라이브러리공식 SDK와 커뮤니티 라이브러리, 그리고 API v2, 지역, 사용자 지정 도메인 지원 여부에 대한 참고 사항입니다.

전체 API 참조v1과 v2의 모든 엔드포인트, 요청 및 응답 스키마, 그리고 계정으로 직접 호출해 볼 수 있는 콘솔입니다.

관련 문서

• 데이터가 저장되는 위치: 지역 선택과 지역 안에 머무는 데이터.
• 사용자 지정 도메인: 자체 도메인에서의 비밀 링크와 API 접근.
• 자체 호스팅: 자체 인프라에서 API 실행.
• 개발자 시작 가이드: 애플리케이션을 로컬에서 실행하고 기여하기.