콘텐츠로 이동

검증



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&timestamp={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 바인딩된 계정에 유효한 워크스페이스 멤버 관계가 없음 해당 워크스페이스 멤버를 찾을 수 없습니다. 해당 계정이 여전히 현재 워크스페이스의 멤버인지 확인하십시오.

문서 평가

이 페이지가 도움이 되었나요?