API 키 관리

API 키는 알림 발송 API(/v1/notifications, /v1/otp 계열)의 HMAC 인증 수단입니다. 키 자체의 발급·수정·회전·폐기는 대시보드 API로 수행하며, Authorization: Bearer 헤더에 대시보드 액세스 토큰을 담아 호출합니다. 토큰 발급은 대시보드 인증을 참고하세요.

키 관리 엔드포인트는 모두 owner / admin 역할만 호출할 수 있습니다.

키 하나는 세 가지 값으로 구성됩니다.

keySecret은 해시로, hmacSecret은 암호화되어 저장되므로 발급·회전 응답에서 단 한 번만 확인할 수 있습니다. 발급 후 실제 요청에 사용하는 방법은 인증을 참고하세요.

스코프

키에 부여할 수 있는 스코프 전체 목록입니다. 생성 시 scopes를 생략하면 notifications:send만 부여됩니다.

스코프가 없는 엔드포인트를 호출하면 403이 반환됩니다.

키 상태

• HMAC 인증은 active 상태의 키만 통과합니다. suspended/revoked 키로 요청하면 401이 반환됩니다.
• 상태 전이는 active → suspended(suspend), suspended → active(resume), active/suspended → revoked(revoke, 회전 포함)만 가능합니다. revoked 키는 resume으로 되살릴 수 없습니다.
• expiresAt이 지난 키는 상태와 무관하게 인증이 401(NOTI-4011)로 거부됩니다.

키 목록 조회

워크스페이스의 모든 키를 최신 생성 순으로 조회합니다. (역할: owner / admin)

{
  "apiKeys": [
    {
      "id": "8f14e45f-…",
      "name": "production-server",
      "keyId": "pk_a1b2c3…",
      "status": "active",
      "expiresAt": null,
      "lastUsedAt": "2026-07-10T09:00:00.000Z",
      "createdAt": "2026-07-01T09:00:00.000Z",
      "scopes": ["notifications:send", "notifications:read"],
      "allowedTemplateIds": [],
      "rateLimit": null
    }
  ]
}

시크릿(keySecret, hmacSecret)은 목록에 포함되지 않습니다. rateLimit은 해당 키 전용 레이트리밋 정책이 있을 때만 채워집니다.

키 생성

새 API 키를 발급합니다. (역할: owner / admin)

curl -X POST https://api.posmit.io/v1/keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-server",
    "expiresInDays": 365,
    "scopes": ["notifications:send", "notifications:read"]
  }'

{
  "apiKeyId": "8f14e45f-…",
  "apiKey": {
    "keyId": "pk_a1b2c3…",
    "keySecret": "f0e1d2…",
    "hmacSecret": "9a8b7c…"
  }
}

키 수정

키의 이름·스코프·템플릿 화이트리스트·만료 시각·전용 한도를 수정합니다. (역할: owner / admin) 지정한 필드만 변경되며, 배열 필드는 전체 교체됩니다.

{
  "apiKey": {
    "id": "8f14e45f-…",
    "name": "production-server",
    "keyId": "pk_a1b2c3…",
    "status": "active",
    "scopes": ["notifications:send"],
    "allowedTemplateIds": ["tmpl-1", "tmpl-2"],
    "rateLimit": null,
    "expiresAt": null,
    "lastUsedAt": null,
    "createdAt": "2026-07-01T09:00:00.000Z"
  }
}

시크릿 회전

기존 키를 폐기하고 같은 설정의 새 키를 발급합니다. (역할: owner / admin)

회전은 다음과 같이 동작합니다.

1. 기존 키는 즉시 revoked 상태가 되어 인증에 사용할 수 없습니다.
2. 새 keyId / keySecret / hmacSecret을 가진 새 자격 증명이 생성됩니다.
3. 스코프, 템플릿 화이트리스트, 키 전용 레이트리밋 정책은 새 키로 승계됩니다.

{
  "apiKey": {
    "keyId": "pk_d4e5f6…",
    "keySecret": "1a2b3c…",
    "hmacSecret": "7d8e9f…"
  }
}

폐기 · 일시정지 · 재개

세 엔드포인트 모두 성공 시 본문 없이 204를 반환하며, 키를 찾을 수 없으면 404(NOTI-40400)가 반환됩니다.

키를 영구 폐기합니다. (역할: owner / admin) 이미 revoked인 키에 호출해도 204가 반환되며(멱등), 폐기된 키는 되돌릴 수 없습니다.

키를 일시정지합니다. (역할: owner / admin) active 상태의 키만 suspended로 바뀌며, 그 외 상태에서는 변경 없이 204가 반환됩니다.

일시정지된 키를 재개합니다. (역할: owner / admin) suspended 상태의 키만 active로 바뀌며, 그 외 상태(폐기 포함)에서는 변경 없이 204가 반환됩니다.

공통 에러

모든 키 관리 엔드포인트는 실패 시 application/problem+json 형식으로 응답합니다.

에러 형식의 자세한 내용은 에러 처리를 참고하세요.