검증¶
POST /api/v1/workspace/accesskey/verify
개요¶
현재 API Key 또는 AccessKey SK token 검증
Body 요청 매개변수¶
| 매개변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| version | any | 신규 SK token 프로토콜 버전; 20260617 전달 시 timestamp만 필요하며 nonce/signature 불필요 예시: 20260617 비워두기 가능: True |
|
| timestamp | integer | Y | 밀리초 타임스탬프, 서버는 10분 이내 요청만 허용 예시: 1711111111000 비워두기 가능: False |
| nonce | string | 구버전 서명 프로토콜 필드; 클라이언트가 생성하는 16-128자 길이의 무작위 문자열, 영문자, 숫자, ., _, :, -만 허용 예시: 2b7c3a9e4f6545b7aef09a23f9e0c001 비워두기 가능: True |
|
| signature | string | 구버전 서명 프로토콜 필드; sk를 사용해 고정 서명 문자열로 계산한 64비트 HMAC-SHA256 hex 소문자 문자열 예시: 3b4d0b1e8f3b6d2d9f30e6f2b7f08f0b2c4f0e9f4f9a6d6c6c7a8b9c0d1e2f3a 비워두기 가능: True |
매개변수 추가 설명¶
이 인터페이스는 현재 요청 헤더 DF-API-KEY의 sk를 검증하는 데 사용됩니다. 검증 통과 후 현재 API Key의 소유 계정, 역할 및 권한 정보를 반환하며, 응답에 ak/sk 필드는 포함되지 않습니다.
version=20260617 신규 프로토콜¶
- 요청 헤더
DF-API-KEY에 현재 OpenAPI 호출에 사용되는sk를 반드시 전달해야 합니다. - 요청 본문에
version=20260617과timestamp를 전달합니다. timestamp는 밀리초 타임스탬프이며, 서버는 현재 시간과의 차이가 10분을 초과하지 않는 요청만 허용합니다.- 신규 버전에서는
nonce와signature가 더 이상 필요하지 않습니다. version은 숫자20260617전달을 권장하며, 서버는 문자열"20260617"도 호환합니다.
구버전 서명 알고리즘¶
- 요청 헤더
DF-API-KEY에 현재 OpenAPI 호출에 사용되는sk를 반드시 전달해야 합니다. version=20260617을 전달하지 않은 경우, 요청 본문에 구버전 방식대로timestamp,nonce,signature를 전달합니다.timestamp는 밀리초 타임스탬프이며, 서버는 현재 시간과의 차이가 10분을 초과하지 않는 요청만 허용합니다.nonce는 클라이언트가 생성하는 16-128자 길이의 무작위 문자열로, 영문자, 숫자,.,_,:,-만 허용됩니다. 동일한 API Key로 기록된 동일한nonce는 10분 이내에 한 번만 사용할 수 있습니다.- 서명 알고리즘은
HMAC-SHA256으로 고정되며, 64비트 hex 소문자 문자열을 출력합니다. - 서명 문자열은 고정 형식:
ak=<ak>&method=POST&nonce=<nonce>&path=/api/v1/workspace/accesskey/verify×tamp=<timestamp>입니다. - 위
<ak>는 호출자가 로컬에 보유하고 있으며 현재sk와 쌍을 이루는지 검증이 필요한ak로, 요청 헤더나 요청 본문에 포함되지 않습니다. signature = HMAC-SHA256-HEX(secret=<sk>, message=<서명 문자열>)입니다.
요청 예시¶
curl 'https://openapi.guance.com/api/v1/workspace/accesskey/verify' \
-H 'DF-API-KEY: <sk>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"version": 20260617, "timestamp": 1711111111000}' \
--compressed
구버전 서명 호출:
curl '<Endpoint>/api/v1/workspace/accesskey/verify' \
-H 'DF-API-KEY: <sk>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"timestamp": 1711111111000, "nonce": "2b7c3a9e4f6545b7aef09a23f9e0c001", "signature": "3b4d0b1e8f3b6d2d9f30e6f2b7f08f0b2c4f0e9f4f9a6d6c6c7a8b9c0d1e2f3a"}' \
--compressed
응답¶
{
"code": 200,
"content": {
"uuid": "wsak_xxx",
"name": "func-ak",
"workspaceUUID": "wksp_xxx",
"createdWay": "manual",
"accountUUID": "",
"accountInfo": null,
"effectiveAccountUUID": "wsak_xxx",
"roles": [
{
"uuid": "readOnly",
"name": "읽기 전용 멤버"
}
],
"permissions": [
"data.query"
],
"rolePermissions": {
"readOnly": [
"data.query"
]
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-XXXX"
}