API 키 관리
Token 형식, 생성 절차, 8개 권한 범위(scopes), 수명 주기, 사용량 분석, 보안 모범 사례입니다.
API 키는 Braidrun 개방형 플랫폼과 통신하기 위한 유일한 자격 증명입니다. 각 키에는 일련의 범위(권한 범위)와 토큰이 포함되어 있습니다. 분실 또는 유출된 경우, 신규 창작물은 즉시 폐기됩니다.
토큰 형식
text
dyk_<id>_<secret>
例：dyk_a3b9c8d7e6f5a1b2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789dyk_— git 비밀 검색/로그 둔감화 도구를 식별 가능하게 만드는 브랜드 접두사<id>— 16자 base62 공개 ID로, lookup key로 사용할 수 있습니다(민감하지 않음)<secret>— 32바이트 무작위 비밀, base64url 인코딩(민감함, 로그/오류 메시지 업로드가 허용되지 않음)
토큰은 한 번만 표시됩니다.
API 키를 생성할 때 원본 토큰은 생성 대화 상자에 한 번만 표시됩니다. 종료 후 서버는 Argon2id 해시만 유지하며 원본 텍스트를 검토할 수 없습니다. 지금 복사하여 키 관리 도구(1Password/Vault/Doppler/GitHub Secrets/etc)에 저장하세요.
API 키 생성
- 콘솔 방문 → 계정 설정 → API 키
- "새 API 키"를 클릭하세요.
- 기재사항 : 이름(식별용), 범위목록, 유효기간(영구/30일/90일/1년)
- "키 생성" → 지금 토큰 복사를 클릭하세요.
범위
Scope는 세분화된 권한으로 총 8개입니다. 7개는 셀프서비스로 부여할 수 있고 CLUSTER_ADMIN은 관리자 전용입니다. 하나의 Key에는 적게 부여할수록 좋으며, 최소 권한 원칙을 따릅니다.
| Scope | 무엇을 할 수 있나요? | 대표 시나리오 |
|---|---|---|
WEBHOOK_TRIGGER | 이 키에 바인딩된 웹훅을 트리거합니다. | GitHub 푸시 → 워크플로; 업스트림 비즈니스 시스템 콜백 |
APPROVAL_RESPOND | manual_approval 단계 승인 / 거부 — 승인 Webhook과 v1 승인 엔드포인트(/api/v1/approvals/*, 대기 중 승인 목록 조회, 상세 읽기, 편집된 승인표 제출 포함)를 아우릅니다 | 이메일 / Slack 원클릭 승인 링크, 외부 승인 시스템 연동 |
WORKFLOW_READ | 워크플로 정의 나열/읽기 | 외부 대시보드에 현재 워크플로 목록 표시 |
WORKFLOW_EXECUTE | API를 통해 워크플로 시작(웹훅 모드 대체) | SDK 통합; 자동화된 테스트; 일괄 작업 |
EXECUTION_READ | 쿼리 실행 상태 / 완료 결과 읽기 | 실행 결과를 엔터프라이즈 BI/데이터 웨어하우스로 백플로우 |
EXECUTION_CANCEL | 실행 중인 실행 취소 | 관리반/비상차단기의 "정지" 버튼 |
ARTIFACT_READ | 실행 제품 나열/다운로드 링크 받기 | 보고서를 객체 스토리지에 보관합니다. 결과를 다운스트림 시스템으로 푸시 |
CLUSTER_ADMIN | 관리자 전용: 클러스터 상태 읽기, 오토스케일링 정책 관리. 관리자만 부여할 수 있으며, 비관리자가 Key를 생성할 때 이 scope는 자동으로 제거됩니다 | 프라이빗 배포의 운영 서비스 계정 |
수명주기
- 창조하다 — 사용자 셀프 서비스 범위 + 유효 기간은 귀하가 결정합니다
- 사용 — 호출이 성공할 때마다 자동으로 사용량이 누적되고 lastUsedAt 타임스탬프가 업데이트됩니다.
- Revoke — 사용자는 언제든지 "API 키" 페이지에서 "해지"를 클릭할 수 있습니다. 멱등성
- 만료 — 만료 시점은 도착 즉시 만료됩니다. 적극적인 철회가 필요하지 않습니다
복용량 분석
각 키에 대해 "API 키" 테이블에서 "사용"을 클릭하면 차트 분석이 나타납니다.
- 누적 통화 수 + 기간 내(7/30/90/180일 선택)
- 피크데이(통화가 가장 많은 날)
- 일일 통화의 꺾은선형 차트
- 호출 엔드포인트 분포 원형 차트(webhook.trigger/workflow.execute/etc)
- 마지막으로 사용한 시간
사용량은 성공적인 응답(HTTP 2xx)만 계산합니다. 인증 실패/속도 제한 요청은 계산되지 않습니다.
주요 보안 모범 사례
준수해주세요
- 각 환경(프로덕션/스테이징/로컬)에 대해 독립 키를 사용합니다. 사고 발생 시 영향을 받은 환경만 취소됩니다.
- 각 외부 통합은 별도의 키를 사용합니다. 사용 중인 통합을 확인하려면 '사용량'을 사용하세요.
- 코드 저장소에 토큰을 제출하지 마십시오.
- CI/CD에 암호화된 비밀로 삽입합니다. 로그에 인쇄하지 않음
- '최근 사용' 시간이 예상과 다른지 확인 → 즉시 취소하고 로그 확인
- 단기 파트너에게 제공되는 키는 만료 시점으로 설정되어야 합니다(90일 이내 권장).