Skip to content

API 키 관리

API 키를 만들고 관리하는 관리자 엔드포인트다. HTTP Basic 인증과 FACE_API_STORAGE_ENABLED=true가 필요하다.

키는 평문으로 저장하며, 관리자 API에서 언제든 확인할 수 있다.

POST /api/v1/admin/api-keys

새 API 키 생성.

요청 본문 (JSON):

{ "name": "운영 앱" }

응답 (201):

{
  "id": "a1b2c3d4-e5f6-...",
  "key": "xyl_7f3a8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e",
  "name": "운영 앱",
  "is_active": true,
  "request_count": 0,
  "last_used_at": null,
  "created_at": "2026-04-06T10:30:00+00:00"
}

예제

curl -u admin:password -X POST \
  https://face-api.xylolabs.com/api/v1/admin/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name": "운영 앱"}'

GET /api/v1/admin/api-keys

API 키 전체 목록과 사용량 조회.

파라미터 타입 기본값 설명
page int 1 페이지 번호
per_page int 20 페이지당 항목 수 (1-100) 
curl -u admin:password https://face-api.xylolabs.com/api/v1/admin/api-keys

GET /api/v1/admin/api-keys/{key_id}

특정 API 키 상세 정보와 사용량 조회.

curl -u admin:password https://face-api.xylolabs.com/api/v1/admin/api-keys/a1b2c3d4-...

PATCH /api/v1/admin/api-keys/{key_id}

키 이름 변경 또는 비활성화/재활성화.

{ "name": "새 이름", "is_active": false }

키 비활성화

curl -u admin:password -X PATCH \
  https://face-api.xylolabs.com/api/v1/admin/api-keys/a1b2c3d4-... \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

DELETE /api/v1/admin/api-keys/{key_id}

API 키를 영구 삭제한다. 204 반환.

curl -u admin:password -X DELETE \
  https://face-api.xylolabs.com/api/v1/admin/api-keys/a1b2c3d4-...

키별 지표

키마다 다음 정보를 추적한다:

필드 설명
request_count 이 키로 호출한 총 횟수
last_used_at 마지막 사용 시각
is_active 키 활성 여부

지표는 요청마다 비동기로 갱신한다.

키 사용법

X-API-Key 헤더에 키를 넣으면 된다:

curl -X POST https://face-api.xylolabs.com/api/v1/detect \
  -H "X-API-Key: xyl_your_key_here" \
  -F "image=@photo.jpg"

비활성 키는 403, 잘못된 키는 401을 반환한다.