검증¶
POST /api/v1/workspace/accesskey/verify
개요¶
현재 호출에 사용되는 Secret Key를 검증하고 ID 및 권한 컨텍스트를 가져옵니다.
호출 전 및 사용 단계¶
현재 OpenAPI Secret Key를 DF_API_KEY로 설정합니다. 새 프로토콜은 version=20260617 및 현재 Unix 밀리초 타임스탬프를 사용합니다. 호출자가 로컬에 저장한 AK/SK 쌍을 검증하려면 이전 프로토콜을 사용하며, 로컬 AK와 SK로 서명을 계산합니다. 유효한 DF-API-KEY를 전달해야만 검증에 도달할 수 있습니다. 인터페이스가 성공하면 ID, 역할 및 권한을 반환하며, 자격 증명 필드는 이 인터페이스에서 반환되지 않습니다. 클라이언트는 여전히 바인딩된 계정 정보를 민감 정보로 처리해야 합니다.
요청 헤더¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 현재 OpenAPI 호출을 시작하는 전체 SK. 예: <SK>가져오기 또는 입력 방법: 워크스페이스 API Key 관리에서 해당 Secret Key의 전체 값을 가져옵니다. |
Body 요청 매개변수¶
| 매개변수 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| version | any | 20260617을 지정하면 SK token 프로토콜을 사용합니다. null 허용: True 예: 20260617가져오기 또는 입력 방법: 새 프로토콜을 사용할 때는 20260617(숫자 또는 문자열)을 입력합니다. 이전 프로토콜을 사용할 때는 생략합니다. |
|
| timestamp | integer | Y | 서버 현재 시간과의 차이는 10분을 초과해서는 안 됩니다. null 허용: False 예: 1785427200000가져오기 또는 입력 방법: 호출 시 시스템 시계로 현재 Unix 밀리초 수를 생성하며, 예시의 정적 숫자는 실제 전송에 사용할 수 없습니다. |
| nonce | string | 이전 프로토콜 필수, 16~128자, 영문자, 숫자 및 . _ : - 사용 가능, 동일 Key의 값은 10분 이내에 중복될 수 없습니다. null 허용: True 예: 2b7c3a9e4f6545b7aef09a23f9e0c001가져오기 또는 입력 방법: 이전 프로토콜에서는 uuid.uuid4().hex로 매번 다른 nonce를 생성할 수 있습니다. |
|
| signature | string | 이전 프로토콜 필수, 64자리 소문자 16진수이며, 예시 값은 자리 표시자입니다. null 허용: True 예: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef가져오기 또는 입력 방법: 로컬 AK를 사용해 서명 원문 계산에 참여하고, SK로 HMAC-SHA256을 수행하여 예시에 따라 생성합니다. |
매개변수 추가 설명¶
예시의 리소스 식별자는 자리 표시자이므로 대상 워크스페이스의 실제 값으로 바꾸십시오.
요청 예시¶
ts=$(python3 -c 'import time; print(int(time.time()*1000))')
curl --fail-with-body "https://openapi.guance.com/api/v1/workspace/accesskey/verify" \
-H "DF-API-KEY: $DF_API_KEY" \
-H "Content-Type: application/json" \
--data-raw "$(printf '{"version":20260617,"timestamp":%s}' "$ts")"
이전 프로토콜 서명 계산 예시
import hmac
import json
import os
import time
import uuid
from urllib.request import Request, urlopen
ak = os.environ["DF_ACCESS_KEY_ID"]
sk = os.environ["DF_API_KEY"]
nonce = uuid.uuid4().hex
timestamp = int(time.time() * 1000)
source = f"ak={ak}&method=POST&nonce={nonce}&path=/api/v1/workspace/accesskey/verify×tamp={timestamp}"
signature = hmac.digest(sk.encode(), source.encode(), "sha256").hex()
payload = {"timestamp": timestamp, "nonce": nonce, "signature": signature}
endpoint = os.environ["OPENAPI_ENDPOINT"].rstrip("/")
request = Request(endpoint + "/api/v1/workspace/accesskey/verify",
data=json.dumps(payload).encode("utf-8"),
headers={"DF-API-KEY": sk, "Content-Type": "application/json"},
method="POST")
with urlopen(request, timeout=15) as reply:
verified = json.load(reply)["content"]
응답¶
HTTP 200, application/json.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.uuid | string | API Key 레코드의 UUID이며 일반적인 접두사는 wsak_입니다. API Key 관리 인터페이스의 경로에 사용됩니다. |
| content.name | string | API Key의 이름. |
| content.workspaceUUID | string | 소속 워크스페이스. |
| content.createdWay | string | API Key의 생성 출처. |
| content.remark | string | API Key의 비고. |
| content.isOwnerRole | integer 또는 boolean | 해당 API Key에 워크스페이스 소유자 역할이 있는지 여부. |
| content.callCount | integer | 기록된 호출 횟수. |
| content.lastCallAt | integer | 마지막으로 기록된 호출 시간, Unix 초, 기록이 없으면 -1일 수 있습니다. |
| content.createAt | integer | 레코드 생성 시간, Unix 초. |
| content.accountUUID | string | 명시적으로 바인딩된 계정 UUID, 바인딩되지 않은 경우 빈 문자열. |
| content.effectiveAccountUUID | string | 인증에 사용되는 ID입니다. 바인딩되지 않은 경우 해당 API Key 레코드 UUID입니다. |
| content.accountInfo | object 또는 null | 바인딩된 계정 정보, 바인딩되지 않은 경우 null. |
| content.roles | array<object> |
유효 역할 집합, 순서는 고정되지 않습니다. |
| content.roles[].uuid | string | 역할 UUID. |
| content.roles[].name | string | 역할 이름. |
| content.permissions | array<string> |
유효 권한 식별자 집합, 순서는 고정되지 않습니다. |
| content.rolePermissions | object | 각 역할이 보유한 권한 식별자로, 역할 UUID를 키로, 권한 문자열 배열을 값으로 합니다. |
| content.declaration | object 또는 null | 워크스페이스 선언. |
{
"code": 200,
"content": {
"uuid": "wsak_example",
"name": "应用数据读取",
"workspaceUUID": "wksp_example",
"createdWay": "manual",
"remark": "",
"isOwnerRole": 0,
"callCount": 14,
"lastCallAt": 1785427200,
"createAt": 1785423600,
"accountUUID": "",
"effectiveAccountUUID": "wsak_example",
"accountInfo": null,
"roles": [
{
"uuid": "role_example",
"name": "应用数据只读"
}
],
"permissions": [
"routine.defaultAccess"
],
"rolePermissions": {
"role_example": [
"routine.defaultAccess"
]
},
"declaration": null
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 필드 유형, 필수 여부 또는 제약 조건이 매개변수 표와 일치하지 않음 | 요청 필드 검증 실패, 메시지에 필드 또는 규칙이 표시됩니다. | 필드, 유형 및 제약 조건을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류. | content의 reason, line, column을 읽은 후 수정하십시오. |
| 400 | ft.JsonFormatError | Body의 JSON 최상위가 객체가 아님 | JSON 형식 오류. | JSON 객체를 전송하십시오. |
| 401 | ft.APIAkKeyFailed | 요청에 인증 헤더가 없음 | 요청 헤더에 AK Key가 없습니다. | DF-API-KEY에 전체 SK를 전달하십시오. |
| 401 | ft.InvalidAPIKey | 자격 증명 또는 버전에 필요한 필드 불일치, 타임스탬프 무효, 이전 서명 부정확 또는 nonce 중복 | 유효하지 않은 API Key. | 자격 증명을 확인하고 시간을 동기화한 후 프로토콜에 따라 서명과 nonce를 다시 생성하십시오. |
| 403 | ft.AgentMemberDisabled | API Key에 바인딩된 계정이 비활성화됨 | 바인딩된 계정을 사용할 수 없습니다. | 바인딩된 계정이 사용 가능한 상태인지 확인하십시오. |
| 404 | ft.AgentMemberNotFound | API Key에 바인딩된 계정이 존재하지 않거나 삭제됨 | 바인딩된 계정을 찾을 수 없습니다. | 바인딩 관계와 계정 상태를 확인하십시오. |
| 404 | ft.WorkspaceAgentMemberNotFound | 바인딩된 계정에 유효한 워크스페이스 멤버 관계가 없음 | 해당 워크스페이스 멤버를 찾을 수 없습니다. | 해당 계정이 여전히 현재 워크스페이스의 멤버인지 확인하십시오. |