삭제¶
POST /api/v1/workspace/accesskey/{ak_uuid}/delete
개요¶
지정한 API Key를 삭제하고 AK/SK를 무효화합니다.
호출 전 준비 및 사용 단계¶
w 권한의 External 자격 증명이 필요합니다. 먼저 API Key 목록 또는 API Key 상세에서 Key 이름과 소속 워크스페이스를 확인하고, 이 자격 증명에 의존하는 모든 클라이언트를 교체한 후 삭제하세요. 이 External 경로는 UUID로 대상을 찾으며 workspaceUUID를 다시 전달할 필요가 없고, 전체 워크스페이스를 삭제하는 파라미터도 허용하지 않습니다. 소프트 삭제를 수행하고 해당 역할 연결을 정리하며 AK/SK 캐시를 무효로 표시합니다. 정상 상태이거나 비활성화되었지만 삭제되지 않은 비시스템 Key를 모두 처리할 수 있으며, Agent Key가 바인딩된 경우 거부됩니다. 존재하지 않거나 이미 삭제되었거나 시스템 Key인 경우 무시되며 여전히 true를 반환할 수 있습니다. true만으로 각 대상이 원래 존재했다고 판단해서는 안 됩니다. 이 작업은 워크스페이스나 수집 Token을 삭제하지 않습니다.
라우트 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| ak_uuid | string | Y | API Key 레코드 UUID(일반적으로 wsak_ 접두사)이며 ak/sk 호출 자격 증명이 아닙니다. 이 External 경로는 UUID로 워크스페이스를 넘나들어 대상을 찾으므로 실행 전에 workspaceUUID를 확인하세요.예: wsak_example001획득 또는 입력 방법: API Key 목록의 content.data[].uuid 또는 생성 성공 시 content.uuid에서 가져옵니다. |
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로와 요청 본문 서명 버전입니다. 생략한 후 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예: v20240417획득 또는 입력 방법: 이 페이지의 예제는 이 고정 버전을 사용하며 예제 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 이 모듈의 목록은 r 또는 w 권한으로 사용할 수 있습니다. 나머지 인터페이스(GET 상세 포함)는 모두 w 권한의 External 자격 증명이 필요합니다. 예: <external-access-key>획득 또는 입력 방법: 사이트 관리자가 할당한 External API AK를 사용하며, 워크스페이스 OpenAPI Key는 사용할 수 없습니다. |
| X-Df-Nonce | string | Y | 임시 일련번호입니다. 실패 후 재전송할 때도 새 값을 생성하고 서명을 다시 계산합니다. 예: 97d275ee9f774315a7885ba7347acbd9획득 또는 입력 방법: 요청할 때마다 uuid.uuid4().hex를 새로 생성합니다. |
| X-Df-Signature | string | Y | 대문자 메서드, nonce, 원본 전체 경로, timestamp, 원본 UTF-8 요청 본문을 공백으로 연결한 후 HMAC-SHA256을 수행하고 hex 다이제스트를 사용합니다. 예: <hmac-sha256-hex>획득 또는 입력 방법: External API 서명 인증에 따라 함께 제공된 SK로 계산하며, 전체 실행 가능한 템플릿은 아래와 같습니다. |
| X-Df-Timestamp | string | Y | 사이트에 구성된 서명 유효 시간 범위 내에 있어야 하며 예제 시간을 재사용할 수 없습니다. 예: 1785427200획득 또는 입력 방법: 전송 시 str(int(time.time()))로 현재 Unix 초 문자열을 생성합니다. |
파라미터 추가 설명¶
사이트 수준 External API AK/SK를 사용하며, 서명 방식은 External API 서명 인증을 참조하세요. 이 페이지에서 생성하는 워크스페이스 API Key와 External 서명 자격 증명은 동일한 자격 증명 세트가 아닙니다. External은 현재 AK/SK를 평문으로 반환하므로 프런트엔드 페이지의 마스킹 정책을 적용하지 않습니다. 응답 예제는 모두 자리 표시자 값을 사용하므로 실제 응답은 자격 증명에 준하여 보관해야 합니다. 삭제를 취소하거나 이전 자격 증명을 복구하는 진입점은 없습니다. 실패 후에는 먼저 Key 상태와 실제 인증을 확인하고, 캐시 새로 고침 예외만으로 Key가 여전히 활성화되어 있다고 판단하지 마세요.
요청 예제¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 대상 사이트 주소 및 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/workspace/accesskey/wsak_example001/delete'
query = {}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
응답¶
HTTP 200, application/json 공통 응답 래퍼이며 비즈니스 결과는 content에 있습니다. External은 declaration을 자동으로 추가하지 않으며, 목록 페이지네이션은 content.pageInfo에 있습니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 성공 시 항상 true를 반환하며, 대상이 존재하지 않거나 이미 삭제되었거나 시스템 Key가 무시된 경우에도 true입니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
아래 표는 확인된 요청 및 비즈니스 분기를 나열합니다. 일반 데이터베이스/캐시/감사 5xx는 전역 래퍼를 거쳐 ft.InternalServerError로 반환됩니다. 쓰기 인터페이스가 오류를 반환할 때 이름, Owner 플래그, 역할 또는 삭제 상태가 이미 저장되었을 수 있으므로 먼저 현재 상태를 조회한 후 다음 단계를 결정해야 합니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인하세요. |
| 400 | ft.AgentWorkspaceAKCanNotDelete | 대상이 createdWay=agent이고 계정에 바인딩된 Key임 | agent에 바인딩된 API Key는 삭제할 수 없습니다 | Agent 관리 절차를 통해 해당 자격 증명을 처리하세요. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시 무효화, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 보관하고 Key의 현재 이름, 역할 및 상태를 확인하세요. 데이터가 먼저 커밋된 후 실패할 수 있으므로 500만으로 적용되지 않았다고 간주할 수 없습니다. |