시작하기
API 키 발급·관리
에이전트 키는 계량소 소장(오너)이 발급하며, 특정 계량소에 바인딩되고 스코프로 권한이 제한됩니다.
발급 흐름
- 소장 콘솔에 오너 계정으로 로그인합니다.
- 키를 바인딩할 계량소와 부여할 스코프를 선택해 에이전트 키를 발급합니다.
- 발급 응답에 단 한 번 노출되는 평문 키(
plainKey)를 안전한 비밀 저장소에 보관합니다. - 이후 API 요청 시 이 키를
Authorization: Bearer헤더로 사용합니다.
평문 키는 재확인이 불가능합니다
서버는 키의 SHA-256 해시만 저장합니다. 평문 키는 발급 응답에서만 볼 수 있으며, 분실 시 복구할 수 없으므로 새 키를 발급해야 합니다.
발급은 오너 로그인(OWNER JWT)으로 인증되는 POST /agent-keys 엔드포인트로 처리됩니다. 아래는 참고용 요청 형태입니다. (실제 발급은 소장 콘솔 UI에서 진행하는 것을 권장합니다.)
키 발급 요청
curl -X POST 'https://api.weighter.shop/agent-keys' \
-H 'Authorization: Bearer <OWNER_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"stationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "정산 자동화 봇",
"scopes": ["read:weighing", "read:payments"]
}'키 발급 응답 (plainKey는 1회만 노출)
{
"success": true,
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "정산 자동화 봇",
"keyPrefix": "wtr_ak_xxxxx",
"scopes": ["read:weighing", "read:payments"],
"expiresAt": null,
"createdAt": "2026-07-11T09:00:00.000Z",
"plainKey": "wtr_ak_xxxxxxxxxxxxxxxxxxxxxxxx"
}
}스코프
키에는 최소 1개 이상의 스코프를 부여합니다. 필요한 최소 권한만 부여하는 것을 권장합니다.
| 스코프 | 권한 |
|---|---|
| read:station | 계량소 정보 조회 |
| read:weighing | 계량 기록 조회 |
| write:weighing | 계량 기록 생성 |
| read:certificates | 증명서 조회 |
| write:certificates | 증명서 발송 요청 |
| read:payments | 결제·미수금 내역 조회 |
폐기
유출이 의심되거나 더 이상 사용하지 않는 키는 즉시 폐기하세요. 폐기된 키로 요청하면 401 AGENT_002가 반환됩니다.
키 폐기 요청
curl -X DELETE 'https://api.weighter.shop/agent-keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
-H 'Authorization: Bearer <OWNER_ACCESS_TOKEN>'보안 수칙
- 키는 서버 환경변수나 비밀 관리 서비스에만 저장하고, 저장소·로그·클라이언트 코드에 포함하지 않습니다.
- 용도별로 키를 분리하고 최소 스코프만 부여합니다.
- 필요 시
expiresAt로 만료 기한을 설정합니다. - 유출 시 즉시 폐기 후 재발급합니다.