조회¶
GET /api/v1/workspace/accesskey/{ak_uuid}/get
개요¶
API Key 레코드 UUID를 기준으로 자격 증명, 바인딩된 ID 및 현재 유효 권한을 조회합니다.
호출 전 및 사용 단계¶
이 인터페이스는 GET이지만 선언상 w 권한의 External 자격 증명이 필요합니다. UUID는 API Key 목록 또는 생성 응답에서 가져옵니다. 추가 workspaceUUID로 제한하지 않으므로 먼저 반환된 content.workspaceUUID를 확인합니다. 수동 Key와 UUID를 알고 있는 비시스템 바인딩 계정 Key 모두 조회할 수 있습니다. 수동 Key의 권한은 해당 역할 관계를 기준으로 하며, 유효한 역할 관계가 없으면 관리자로 폴백할 수 있습니다. 바인딩 계정 Key의 권한은 계정의 워크스페이스 역할에 따라 변경됩니다. 반환된 roles/permissions/rolePermissions가 유효 권한 요약이며, 생성 또는 수정 시의 roleInfo 빈 배열만으로 권한이 없다고 판단해서는 안 됩니다. 조회는 Key를 소모하거나 삭제하지 않습니다.
라우트 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| 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 평문을 반환하며 프런트 화면의 마스킹 정책을 적용하지 않습니다. 응답 예시는 모두 자리표시자 값을 사용하므로 실제 응답은 자격 증명으로 보관해야 합니다.
요청 예시¶
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 = 'GET'
path = '/api/v1/workspace/accesskey/wsak_example001/get'
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.id | integer 또는 null | 내부 레코드 일련번호이며, 인터페이스 호출에는 uuid를 사용합니다. 생성 스냅샷은 flush 전에 가져오므로 이 필드는 null일 수 있습니다. |
| content.uuid | string | API Key 레코드 UUID이며 호출 자격 증명 ak/sk와 다릅니다. |
| content.status | integer | Key 상태: 0 활성, 2 비활성, 3 삭제됨. 목록/상세는 0만 반환하며, 삭제는 삭제되지 않은 비활성 Key도 처리할 수 있습니다. |
| content.creator | string | 생성 ID이며, External 생성은 보통 external입니다. |
| content.updator | string | 수정 ID이며, 수정되지 않은 경우 비어 있을 수 있습니다. |
| content.createAt | integer | 생성 Unix 초. |
| content.deleteAt | integer | 삭제 Unix 초, 삭제되지 않은 경우 보통 -1. |
| content.updateAt | integer | 수정 Unix 초, 아직 수정되지 않은 경우 보통 -1. |
| content.name | string | API Key 표시 이름. |
| content.ak | string | 워크스페이스 Access Key 호출 자격 증명 평문이며, 해당 워크스페이스 OpenAPI 인증에 사용할 수 있고 이 External 요청의 X-Df-Access-Key가 아닙니다. |
| content.sk | string | 워크스페이스 Secret Key 평문이며 민감한 자격 증명으로 보관해야 합니다. 이 External 요청의 대응하는 SK가 아닙니다. |
| content.workspaceUUID | string | 소속 워크스페이스 UUID. |
| content.accountUUID | string | 바인딩 계정 UUID이며, 수동 워크스페이스 Key는 빈 문자열입니다. 바인딩 계정 Key의 유효 권한은 계정 역할로 확인해야 합니다. |
| content.createdWay | string | 출처 식별자, 예: manual, user, agent. 목록은 accountUUID가 비어 있지 않은 모든 Key를 제외합니다. |
| content.businessType | string | 시스템 비즈니스 유형 식별자이며, 수동 Key는 보통 비어 있습니다. |
| content.isSystem | integer | 시스템 내장 Key 여부이며, 이 모듈의 조회/작업은 시스템 Key를 필터링합니다. |
| content.isOwnerRole | integer | Owner 전용 Key 여부, 1은 예, 0은 아니요. 동일 워크스페이스에 삭제되지 않은 Owner Key는 최대 하나입니다. |
| content.remark | string | 기존 비고이며, 이 External 공개 추가/수정 파라미터에는 remark가 포함되지 않습니다. |
| content.isBurnAfterReading | integer | 보존된 열람 후 소멸 플래그이며, 이 모듈은 조회 후 소멸을 실행하지 않으므로 이를 의존해 자격 증명을 폐기해서는 안 됩니다. |
| content.callCount | integer 또는 null | 영구 누적 호출 횟수이며 비동기 집계로 실시간 카운트가 아닙니다. 생성 스냅샷은 flush 전에 null일 수 있습니다. |
| content.lastCallAt | integer 또는 null | 마지막 호출 Unix 초, 보통 -1은 기록 없음을 의미합니다. 생성 스냅샷은 null일 수 있습니다. |
| content.creatorInfo | object | 생성 ID 요약이며, 확인할 수 없는 경우 {}이고 필드는 ID 유형에 따라 달라집니다. |
| content.creatorInfo.uuid | string | 생성 ID UUID, 시스템 ID는 비어 있을 수 있습니다. |
| content.creatorInfo.status | integer | 생성 ID 상태. |
| content.creatorInfo.wsAccountStatus | integer | 워크스페이스 관계 상태 요약이며, 시스템 ID는 0일 수 있습니다. |
| content.creatorInfo.username | string | 사용자 이름 또는 시스템 ID 이름. |
| content.creatorInfo.name | string | 표시 이름. |
| content.creatorInfo.email | string | 이메일 또는 시스템 ID 식별자. |
| content.creatorInfo.mobile | string | 휴대폰 번호, 시스템 ID는 비어 있습니다. |
| content.creatorInfo.countryCode | string | 계정 ID가 제공할 수 있는 휴대폰 국가 코드이며, 시스템 ID는 생략될 수 있습니다. |
| content.creatorInfo.iconUrl | string | 계정 ID가 제공할 수 있는 아바타이며, 시스템 ID는 생략될 수 있습니다. |
| content.creatorInfo.acntWsNickname | string | 계정 ID가 제공할 수 있는 워크스페이스 닉네임이며, 시스템 ID는 생략될 수 있습니다. |
| content.effectiveAccountUUID | string | 인증 역할 주체이며, 수동 Key는 Key 자체 uuid, 바인딩 계정 Key는 accountUUID입니다. |
| content.accountInfo | object 또는 null | 바인딩 계정인 경우 password/mfaSecret을 제거한 계정 정보를 반환하며, 수동 Key는 null입니다. |
| content.accountInfo.id | integer | 사이트 내 계정 레코드 일련번호이며 정보 반환용으로만 사용합니다. 다른 인터페이스 호출에는 uuid를 사용합니다. |
| content.accountInfo.uuid | string | 계정 UUID이며, 이후 조회, 수정, 비활성화, 삭제에 이 필드를 사용합니다. |
| content.accountInfo.status | integer | 바인딩 계정 상태: 성공 시 0 또는 기타 비활성화되지 않은 이전 상태를 반환할 수 있으며, 2는 먼저 ft.AgentMemberDisabled를, 3 또는 존재하지 않음은 먼저 ft.AgentMemberNotFound를 트리거합니다. |
| content.accountInfo.creator | string | 생성 ID 식별자이며, External 생성은 보통 SYS입니다. |
| content.accountInfo.updator | string | 최근 수정 ID 식별자이며, 아직 수정이 없으면 비어 있을 수 있습니다. |
| content.accountInfo.createAt | number | 생성 시간, Unix 초. |
| content.accountInfo.updateAt | number | 수정 시간, Unix 초, 아직 수정 시간이 없으면 -1일 수 있습니다. |
| content.accountInfo.deleteAt | number | 상태 작업 시간 필드, 초기에는 보통 -1입니다. 활성화/비활성화 시에도 이 값이 기록되므로 단독으로 삭제를 판단하지 말고 status를 사용하세요. |
| content.accountInfo.name | string | 표시 닉네임. |
| content.accountInfo.username | string | 로그인 계정 이름. 서드파티 계정은 비어 있거나 다른 계정과 중복될 수 있습니다. |
| content.accountInfo.email | string | 계정 연락 이메일이며, 생성 시 비어 있고 username이 이메일 형식이면 username으로 보충됩니다. |
| content.accountInfo.mobile | string | 휴대폰 번호 로컬 번호이며 복호화되어 표시되고 국가 코드는 포함하지 않습니다. 설정되지 않으면 빈 문자열입니다. |
| content.accountInfo.countryCode | string | 휴대폰 번호 국가/지역 코드 순수 숫자 문자열, 예: 86. 설정되지 않으면 빈 문자열입니다. |
| content.accountInfo.exterId | string | 서드파티 ID 시스템의 고유 ID이며, 로컬 계정은 보통 비어 있습니다. |
| content.accountInfo.extend | object 또는 null | 바인딩 계정의 기존 확장 정보이며 user_icon 아바타 주소를 포함할 수 있습니다. 이 페이지는 반환만 하며 Key 파라미터로 수정할 수 없습니다. |
| content.accountInfo.extend.user_icon | string | 선택적 아바타 URL 또는 정적 리소스 파일명이며, 기존 정보를 읽을 때 나타날 수 있고 이 페이지에서 쓸 수 있는 파라미터가 아닙니다. |
| content.accountInfo.source | string | ID 출처 식별자, 예: local, unknown, oidc, ldap. agent 등 기존 내부 출처도 존재할 수 있습니다. |
| content.accountInfo.nameSpace | string | ID 네임스페이스이며, External 생성 시 기본값은 비어 있습니다. 이 모듈의 공개 파라미터로 설정할 수 없습니다. |
| content.accountInfo.isUsed | integer 또는 boolean | 계정 사용 여부 플래그. |
| content.accountInfo.agreeTerms | integer | 약관 동의 플래그. |
| content.accountInfo.canaryPublic | boolean | 카나리 플래그. |
| content.accountInfo.enableMFA | boolean | MFA 사용 여부. |
| content.accountInfo.language | string | 언어 식별자, zh, en, zh-hant, id, ja, ko. |
| content.accountInfo.tokenHoldTime | integer | 계정 무작업 세션 유지 시간, 단위 초. 신규 계정은 사이트 보안 세션 구성에 따라 초기화되며 예시 값으로 고정된다고 보장하지 않습니다. |
| content.accountInfo.tokenMaxValidDuration | integer | 계정 세션 최대 유효 기간, 단위 초. 신규 계정은 사이트 보안 세션 구성에 따라 초기화됩니다. |
| content.accountInfo.timezone | string | 시간대 식별자, 설정되지 않으면 비어 있습니다. |
| content.accountInfo.attributes | object | SSO 동기화 속성 KV 객체이며 이후 SSO 로그인으로 덮어쓸 수 있습니다. 키와 값은 연동 측에서 정의합니다. |
| content.accountInfo.attributes.{속성명} | 임의의 JSON 값 | 사용자 정의 속성 값이며 문자열 사용을 권장합니다. 예: 部门=研发部. |
| content.accountInfo.customAttributes | object | 비즈니스 측에서 유지 관리하는 속성 KV 객체. |
| content.accountInfo.customAttributes.{속성명} | 임의의 JSON 값 | 비즈니스 사용자 정의 값이며 문자열 사용을 권장합니다. 예: costCenter=CC-1001. |
| content.accountInfo.statusPageSubs | integer | 상태 페이지 구독 플래그. |
| content.accountInfo.defaultWorkspace | string | 계정 기본 워크스페이스 UUID, 구성되지 않으면 비어 있습니다. |
| content.accountInfo.brandKey | string | 계정의 현재 브랜드 식별자이며, 사이트에서 허용된 브랜드 집합에 의해 결정됩니다. |
| content.accountInfo.scheduleMobile | string | 온콜 전용 휴대폰 번호 로컬 번호, 설정되지 않으면 비어 있습니다. |
| content.accountInfo.scheduleEmail | string | 온콜 전용 이메일, 설정되지 않으면 비어 있습니다. |
| content.accountInfo.ifScheduleMobileEnable | boolean | 온콜 휴대폰 번호 사용 여부. |
| content.accountInfo.ifScheduleEmailEnable | boolean | 온콜 이메일 사용 여부. |
| content.accountInfo.accountStatus | string | 계정 추가 상태 식별자, 설정되지 않으면 비어 있습니다. |
| content.roles | 객체 배열 | 현재 유효 역할 요약이며, Owner 전용 Key는 Owner 역할입니다. |
| content.roles[].uuid | string | 역할 UUID. |
| content.roles[].name | string | 역할 이름. |
| content.permissions | 문자열 배열 | 현재 유효 권한 식별자이며 순서는 보장되지 않습니다. |
| content.permissions[] | string | 하나의 유효 권한 ID. |
| content.rolePermissions | object | 역할 UUID를 키로 하는 전체 유효 권한 매핑. |
| content.rolePermissions.{역할 UUID} | 문자열 배열 | 해당 역할의 현재 유효 권한 ID 목록이며, 동적 역할 키는 roles[].uuid에서 가져옵니다. |
| content.rolePermissions.{역할 UUID}[] | string | 단일 권한 ID. |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wsak_example001",
"status": 0,
"creator": "external",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例只读API Key",
"ak": "<workspace-api-key>",
"sk": "<workspace-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "",
"createdWay": "manual",
"businessType": "",
"isSystem": 0,
"isOwnerRole": 0,
"remark": "",
"isBurnAfterReading": 0,
"callCount": 0,
"lastCallAt": -1,
"creatorInfo": {
"uuid": "",
"status": 0,
"name": "SYS",
"wsAccountStatus": 0,
"username": "SYS",
"email": "SYS",
"mobile": ""
},
"effectiveAccountUUID": "wsak_example001",
"accountInfo": null,
"roles": [
{
"uuid": "role_example001",
"name": "示例最小权限角色"
}
],
"permissions": [
"routine.defaultAccess"
],
"rolePermissions": {
"role_example001": [
"routine.defaultAccess"
]
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
바인딩 계정 Key의 구조 예시(실제 권한은 바인딩 계정에 따라 달라집니다):
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wsak_example001",
"status": 0,
"creator": "external",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例只读API Key",
"ak": "<workspace-api-key>",
"sk": "<workspace-secret-key>",
"workspaceUUID": "wksp_example001",
"accountUUID": "acnt_example001",
"createdWay": "agent",
"businessType": "",
"isSystem": 0,
"isOwnerRole": 0,
"remark": "",
"isBurnAfterReading": 0,
"callCount": 0,
"lastCallAt": -1,
"creatorInfo": {
"uuid": "",
"status": 0,
"name": "SYS",
"wsAccountStatus": 0,
"username": "SYS",
"email": "SYS",
"mobile": ""
},
"effectiveAccountUUID": "acnt_example001",
"accountInfo": {
"id": 1001,
"uuid": "acnt_example001",
"status": 0,
"creator": "SYS",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例Agent",
"username": "agent-example",
"email": "",
"mobile": "",
"countryCode": "",
"exterId": "",
"extend": null,
"source": "agent",
"nameSpace": "",
"isUsed": 0,
"agreeTerms": 0,
"canaryPublic": false,
"enableMFA": false,
"language": "zh",
"tokenHoldTime": 86400,
"tokenMaxValidDuration": 604800,
"timezone": "",
"attributes": {
"部门": "研发部"
},
"customAttributes": {
"costCenter": "CC-1001"
},
"statusPageSubs": 0,
"defaultWorkspace": "",
"brandKey": "guance",
"scheduleMobile": "",
"scheduleEmail": "",
"ifScheduleMobileEnable": false,
"ifScheduleEmailEnable": false,
"accountStatus": ""
},
"roles": [
{
"uuid": "role_example001",
"name": "示例最小权限角色"
}
],
"permissions": [
"routine.defaultAccess"
],
"rolePermissions": {
"role_example001": [
"routine.defaultAccess"
]
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
다음 표는 확인된 요청 및 비즈니스 분기를 나열합니다. 일반 데이터베이스/캐시/감사 5xx는 전역 래퍼를 통해 ft.InternalServerError로 반환됩니다. 쓰기 인터페이스가 오류를 반환할 때 이름, Owner 플래그, 역할 또는 삭제 상태가 이미 저장되었을 수 있으므로 먼저 현재 상태를 조회한 후 다음 단계를 결정해야 합니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락, 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입 및 값을 확인합니다. |
| 404 | ft.AKNotExistOrDelete | UUID에 대응하는 활성 비시스템 API Key가 없거나 Key가 이미 삭제/비활성화됨 | 지정한 AK가 존재하지 않거나 이미 삭제됨 | 목록에서 대상 uuid를 다시 가져옵니다. 목록은 바인딩 계정 Key를 표시하지 않으며, 시스템 내장 Key는 이 진입점으로 관리할 수 없습니다. |
| 404 | ft.AgentMemberNotFound | 바인딩 계정 UUID에 해당하는 계정이 존재하지 않거나 삭제됨 | agent에 해당하는 사용자를 찾을 수 없음 | 해당 계정 관리 진입점에서 계정과 Key 바인딩을 확인하고, 수동 Key로 처리하지 마세요. |
| 403 | ft.AgentMemberDisabled | 바인딩 계정이 비활성 상태 | agent에 해당하는 사용자가 비활성화됨 | 먼저 해당 계정 관리 프로세스를 통해 상태를 처리합니다. |
| 404 | ft.WorkspaceAgentMemberNotFound | 바인딩 계정에 해당 워크스페이스의 활성 직접 멤버 관계가 없음 | 해당 agent에서 agent에 해당하는 사용자를 찾을 수 없음 | 해당 계정/Agent 관리 진입점에서 워크스페이스 멤버 바인딩을 확인합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시 무효화, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 보관하고 Key의 현재 이름, 역할 및 상태를 확인합니다. 데이터가 먼저 커밋된 후 실패할 수 있으므로 500만으로 적용되지 않았다고 판단할 수 없습니다. |