9. Admin API

LOCAL 인증 모드에서만 제공되는 관리자 전용 API이다. 최초 Admin API Key 발급은 /api/setup/ 엔드포인트를 통해 수행하며, 이후 /api/admin/api-keys/로 API키를 관리한다.

9.1 API 키 생성

엔드포인트 :

POST /api/admin/api-keys

필요 권한 : ADMIN

요청 바디 :

필드	타입	필수	설명
clientId	string	필수	API 키가 속할 클라이언트(테넌트) ID
role	string	필수	권한 목록 (쉼표로 구분된 문자열)
description	string	선택	API 키에 대한 설명

Note

값	설명
READ	조회 권한
WRITE	데이터 수정 권한
CREATE	생성 권한
DROP	삭제 권한
SHARED	공유 권한
ADMIN	관리자 권한

예제

curl -X POST http://localhost:8080/api/admin/api-keys \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "mobileApp",
    "role": "READ,WRITE,CREATE",
    "description": "모바일 앱용 API 키"
  }'

응답 (201 Created):

{
  "clientId": "mobileApp",
  "apiKey": "generated_api_key_here",
  "role": "READ,WRITE,CREATE",
  "description": "모바일 앱용 API 키",
  "message": "API key created successfully. Please save this key as it will not be shown again."
}

Warning

생성된 API 키는 이 응답에서만 확인할 수 있으므로, 반드시 안전한 곳에 저장해야 한다.

9.2 API 키 목록 조회

엔드포인트 :

GET /api/admin/api-keys

필요 권한 : ADMIN

쿼리 파라미터 :

파라미터	설명	기본값
page	페이지 번호	1
size	페이지 크기	10
keyword	검색 키워드 (clientId, description)

예제

clientId 또는 description에 "mobile"이라는 키워드가 포함된 API 키를 검색하여, 페이지당 20개의 결과 중 첫번째 페이지를 요청하는 예제이다.

curl -X GET "http://localhost:8080/api/admin/api-keys?page=1&size=20&keyword=mobile" \
  -H "Authorization: Bearer ${TOKEN}" 

응답 (200 OK):

{
  "keys": [
    {
      "clientId": "mobileApp",
      "role": "CLIENT",
      "permissions": "READ,WRITE,CREATE",
      "description": "모바일 앱용 API 키",
      "createdBy": "admin",
      "createdAt": "2025-01-10T09:00:00",
      "expiresAt": null,
      "active": true,
      "lastUsedAt": null,
      "requestCount": 150
    }
  ],
  "total": 1
}

Note

위 응답에서 role은 시스템 역할(CLIENT 또는 ADMIN)이고, 실제 Global Authority 집합은 permissions 필드에 포함된다. 반면, 생성/권한 수정 요청에서는 하위 호환을 위해 role 필드에 권한 문자열을 전달한다.

9.3 API 키 삭제

엔드포인트 :

DELETE /api/admin/api-keys/{clientId}

필요 권한 : ADMIN

예제

curl -X DELETE http://localhost:8080/api/admin/api-keys/mobileApp \
  -H "Authorization: Bearer ${TOKEN}"

응답 (200 OK):

{
  "message": "API key deleted successfully",
  "clientId": "mobileApp"
}

9.4 API 키 폐기

엔드포인트 :

PUT /api/admin/api-keys/{clientId}/revoke

필요 권한 : ADMIN

예제

curl -X PUT http://localhost:8080/api/admin/api-keys/mobileApp/revoke \
  -H "Authorization: Bearer ${TOKEN}"

응답 (200 OK):

{
  "message": "API key revoked successfully",
  "clientId": "mobileApp"
}

9.5 API 키 권한 수정

엔드포인트 :

PUT /api/admin/api-keys/{clientId}/permissions

필요 권한 : ADMIN

요청 바디 :

필드	타입	필수	설명
role	string	필수	변경할 권한 목록 (쉼표로 구분된 문자열)

예제

curl -X PUT http://localhost:8080/api/admin/api-keys/mobileApp/permissions \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"role": "READ,WRITE,DROP"}'

응답 (200 OK):

{
  "message": "API key permissions updated successfully",
  "clientId": "mobileApp",
  "permissions": "READ,WRITE,DROP"
}

9.6 테넌트 DB 계정 생성

특정 클라이언트(테넌트)가 데이터베이스에 직접 접속할 수 있는 전용 계정을 생성한다.

엔드포인트 :

POST /api/admin/api-keys/{clientId}/db-account

필요 권한 : ADMIN

요청 바디 :

필드	타입	필수	설명
password	string	필수	클라이언트(테넌트) 전용 데이터베이스 접속 계정의 비밀번호

{
  "password": "strong_password_123!"
}

예제

curl -X POST http://localhost:8080/api/admin/api-keys/mobileApp/db-account \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"password": "db_password_123!"}'

응답 (200 OK): 빈 응답