인증

API는 조직 API 키로 서버를 인증합니다. 키는 (개인이 아닌) 조직에 속하고, 일련의 권한을 가지며, 테스트 또는 라이브 중 정확히 하나의 모드에서만 작동합니다.

키 보내기

다음 헤더 중 하나를 사용하세요.

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

키는 bf_live_… 또는 bf_test_… 형식입니다. 키가 없으면 401(unauthorized)이 반환되며, 형식이 잘못되었거나 폐기되었거나 만료된 키도 401입니다. 키는 서버에만 보관하고 브라우저나 모바일 앱에는 절대 포함하지 마세요. 브라우저에서 서명하려면 대신 서명 세션을 발급하세요.

테스트 키와 라이브 키

	테스트(`bf_test_…`)	라이브(`bf_live_…`)
문서	`TEST` 워터마크와 함께 렌더링	워터마크 없음
이메일	조직 구성원에게만 전송	모든 수신자에게 전송
청구	무료 무제한, 사용량에 포함되지 않음	완료된 봉투가 플랜 사용량에 포함됨
데이터	키로 만든 봉투, 링크, 웹훅 엔드포인트는 테스트 모드	라이브 모드

모드는 요청이 아니라 항상 키에 따라 결정됩니다. POST /v1/envelopes의 ?test_mode=true는 대시보드 세션에만 적용됩니다. 목록(GET /v1/envelopes, GET /v1/signing-links)은 키와 같은 모드의 항목만 반환하며, 봉투의 이벤트는 같은 모드의 웹훅 엔드포인트로만 전송됩니다. 모든 봉투와 웹훅 페이로드에는 어떤 모드인지 표시됩니다(testMode).

키 만들기와 폐기

키는 대시보드의 설정 › API 키에서 apikey:manage 권한이 있는 구성원(소유자 및 관리자)이 관리합니다. 시크릿은 키를 만들 때 한 번만 표시됩니다. 키에는 이름, 모드, 만료 기간(1~365일 또는 없음), 스코프를 지정할 수 있습니다.

스코프

키의 스코프는 그 키가 사용할 수 있는 조직 권한입니다. 기본적으로 새 키에는 생성자의 권한에서 관리 권한(org:manage, member:manage, sso:manage, apikey:manage, billing:manage)을 뺀 권한이 부여되며, 누구도 자신에게 없는 권한을 키에 부여할 수 없습니다. 키의 스코프를 벗어난 호출은 403이 되며, 누락된 권한이 표시됩니다.

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

권한	키로 할 수 있는 작업
`template:read`	템플릿, 버전 및 해당 PDF 목록 조회와 읽기
`template:write`	템플릿 생성, 파일 업로드, 초안 저장, 사용되지 않은 템플릿 삭제
`template:publish`	초안을 새 버전으로 게시
`envelope:read`	봉투, 문서, 감사 추적 목록 조회와 읽기, 서명 링크 목록 조회
`envelope:send`	봉투, 서명 세션, 서명 링크 생성, 링크 재전송
`envelope:void`	진행 중인 봉투 무효화
`org:manage`	웹훅 엔드포인트 관리와 이벤트 재전송, 조직 설정 읽기
`billing:manage`	사용량(`GET /v1/usage`) 및 청구 금액 읽기

웹훅 엔드포인트를 관리하려면 org:manage가 필요한데, 이 권한은 기본적으로 키에 부여되지 않습니다. 엔드포인트는 대시보드에서 등록하거나, 이 스코프를 명시적으로 지정한 키를 만드세요.

엔드포인트별 인증 방식

API 레퍼런스의 각 작업에는 해당 보안 스킴이 나와 있습니다. 요약하면 다음과 같습니다.

API 키 또는 대시보드 세션: 템플릿, 봉투, 서명 세션, 서명 링크, 웹훅 엔드포인트, 조직 설정, 청구 개요 및 사용량.
대시보드 세션만: API 키, SCIM 토큰, SSO 연결 설정, 조직 로고 업로드, 청구 결제 및 포털, 웹훅 시크릿 표시.
서명자 토큰: /v1/signing/*. 호스팅 페이지와 <bf-signing>이 세션 토큰(bfs_…) 또는 그것과 교환한 액세스 토큰(bfa_…)으로 사용합니다.
공개: /v1/links/{id}(상시 링크), /v1/sso/discover, 그리고 검증 API (/v1/public/*, /.well-known/bona-fide/keys.json).

대시보드 로그인

(서버가 아닌) 사람은 https://app.bonafidesign.com/sign-in에서 대시보드에 로그인합니다. 기본 방식은 이메일과 비밀번호이며, 그 밖에 이메일로 받는 6자리 코드(대신 이메일로 코드 받기), 매직 링크, 패스키, Google 또는 Microsoft, 회사 SSO를 사용할 수 있습니다.

비밀번호로 계정을 만들면 이메일이 한 통 전송됩니다. 그 주소가 본인 소유임을 확인하는 코드입니다. 확인하기 전까지는 그 비밀번호로 로그인할 수 없습니다. 이미 계정이 있는 주소로 가입해도 아무것도 바뀌지 않으며 신규 가입과 똑같은 응답이 반환됩니다. 대신 그 주소의 소유자에게 로그인 방법을 안내하는 이메일이 전송됩니다.
비밀번호는 12~128자이며 솔트가 적용된 scrypt 해시로 저장됩니다. 알려진 데이터 유출에 포함된 새 비밀번호는 거부됩니다. Have I Been Pwned에는 SHA-1 해시의 앞 5자만 전송되며(k-익명성) 비밀번호 자체는 절대 전송되지 않습니다. 이 서비스가 2초 안에 응답하지 않으면 확인 없이 비밀번호가 허용됩니다.
비밀번호를 잊으셨나요? 재설정 이메일의 링크를 열면 새 비밀번호를 정하는 페이지로 이동합니다. 링크는 한 번만 사용할 수 있고 1시간 후 만료되며, 링크를 사용하면 모든 기기에서 로그아웃됩니다.
아직 비밀번호가 없나요? 코드, 링크, 패스키, Google / Microsoft로 만든 계정은 계속 그 방식으로 로그인할 수 있으며, 설정 › 계정에서 비밀번호를 추가할 수 있습니다. 처음 비밀번호를 설정하려면 최근 15분 이내에 로그인한 상태여야 하고(본인 확인을 위해 페이지에서 코드를 이메일로 보냅니다), 변경하려면 현재 비밀번호가 필요합니다. 두 경우 모두 다른 세션은 로그아웃됩니다.
오류로 계정 존재 여부가 드러나지 않습니다: 잘못된 비밀번호, 등록되지 않은 주소, 비밀번호가 없는 계정에는 모두 같은 응답이 반환되며, 재설정 요청에는 항상 이메일을 보냈다고 응답합니다.
속도 제한: 비밀번호 로그인, 가입, 재설정 요청은 IP 주소별, 이메일 주소별로 제한됩니다. 한도를 넘으면 해당 기간이 지날 때까지 429가 반환됩니다.
회사 SSO: 조직이 SSO를 강제 적용하면 해당 조직의 이메일 도메인 구성원은 ID 공급자를 통해서만 로그인할 수 있습니다. 이들에게는 비밀번호, 코드, 매직 링크가 거부되며, 소유자는 비상용 로그인 수단으로 이메일 코드를 계속 사용할 수 있습니다.

요청 ID

모든 응답에는 x-request-id 헤더가, 모든 오류 본문에는 requestId가 포함됩니다. 로그를 연결하기 위해 직접 x-request-id(A-Z a-z 0-9 . _ -로 구성된 8~128자)를 보낼 수도 있으며, 보내지 않으면 API가 생성합니다. 지원팀에 문의할 때 이 ID를 알려 주세요.