로테이션¶
POST /api/v1/workspace/accesskey/{ak_uuid}/rotate
개요¶
현재 워크스페이스의 지정된 수동 API Key를 로테이션하며, 리소스 UUID와 역할 구성을 유지합니다.
호출 전 및 사용 단계¶
현재 워크스페이스에서 workspace.openAPIKeyManage 권한을 가진 OpenAPI Key를 사용합니다. 라우트 선언에는 freeEdition 버전 제한이 표시되어 있지만, 현재 OpenAPI 인증 체인은 해당 버전 검사를 수행하지 않으므로 버전 자체를 반드시 403이라고 설명할 수는 없습니다. 가용성은 배포 및 실제 권한에 따라 확인해야 합니다. 리소스 범위는 항상 요청 헤더 Key가 속한 워크스페이스에서 가져오며, Body로 워크스페이스를 전환할 수 없습니다. owner Key는 현재 ID에 owner가 포함되어야 하며, 인터페이스 관리 권한 자체가 이 검사를 대체하지 않습니다.
현재 워크스페이스에서 활성 상태이고 시스템이 아니며 accountUUID가 빈 수동 Key를 먼저 찾은 후, 새 자격 증명을 수신할 준비를 하고 이를 사용하는 자동화/SDK와 조정합니다. 요청에는 Body가 필요하지 않습니다. 새 ak/sk를 생성하여 저장하고 uuid, 이름, 비고, 역할, 생성 시간 및 호출 통계를 유지한 다음 새 Key 캐시를 갱신하고 기존 ak/sk를 무효화합니다. 성공 후 기존 자격 증명은 계속 사용할 수 없으며, 이미 시작된 요청은 철회가 보장되지 않습니다.
현재 Key는 자기 자신을 로테이션할 수 있으며, 현재 요청은 이미 인증되었으므로 완료한 뒤 반환된 새 자격 증명으로 전환할 수 있습니다. 새 자격 증명이 성공적으로 저장된 후 호출자를 업데이트하여 마지막 관리 Key를 잃지 않도록 합니다. 생성 및 로테이션 응답에는 ak/sk 평문이 포함되므로 즉시 통제된 자격 증명 저장소에 기록해야 합니다. OpenAPI 인증 헤더는 Key 값을 사용하며(예: 반환된 sk), wsak_ 리소스 UUID를 사용하지 않습니다. 이후 목록/상세는 호출 ID, 대상이 수동/바인딩 계정인지 및 현재 Key인지 여부의 영향을 받아 마스킹될 수 있습니다. 이후 읽기로 손실된 자격 증명을 복구해서는 안 되며, 현재 서비스 구현을 모든 ID가 다시는 평문을 반환하지 않는다고 설명할 수도 없습니다.
로테이션은 멱등적이지 않으며, 매번 새로운 값 한 쌍으로 교체됩니다. 데이터베이스 커밋 후 캐시 무효화가 실패하면 500이 반환될 수 있으며, 이때 기존 자격 증명이 잠시 동안 계속 사용 가능한지는 오류 코드만으로 판단할 수 없습니다. 다른 유효한 관리 Key로 다시 읽거나 다시 로테이션하여 처리해야 하며, 재시도를 동일한 결과의 재생으로 간주해서는 안 됩니다.
라우트 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| ak_uuid | string | Y | 현재 워크스페이스의 Key 리소스 UUID이며, ak/sk 평문 또는 다른 워크스페이스 UUID를 입력할 수 없습니다. 예시: wsak_example획득 또는 입력 방법: API Key 목록의 content[].uuid 또는 생성 응답의 content.uuid에서 가져오며, 필요한 경우 API Key 상세로 확인합니다. |
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
파라미터 추가 설명¶
로테이션은 새 ak/sk를 반환하므로 즉시 안전하게 저장하고 사용 측을 교체해야 합니다. 기존 자격 증명은 로테이션 및 캐시 무효화가 완료된 후에는 계속 사용할 수 없습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/accesskey/wsak_example/rotate' \
-H 'DF-API-KEY: <DF-API-KEY>'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.id | integer 또는 null | 데이터베이스 번호이며, 생성 응답은 커밋 전 스냅샷이므로 null일 수 있습니다. 이후 작업에는 uuid를 사용합니다. |
| content.uuid | string | wsak_로 시작하는 API Key 리소스 UUID로, 상세/삭제/로테이션 경로에 사용됩니다. DF-API-KEY의 값이 아닙니다. |
| content.workspaceUUID | string | 현재 호출 Key가 속한 워크스페이스 UUID입니다. |
| content.name | string | Key 이름입니다. |
| content.ak | string | 새로 생성된 ak 평문입니다. 리소스 uuid가 아니며, 호출 서비스의 자격 증명 규약에 따라 사용합니다. |
| content.sk | string | 새로 생성된 sk 평문이며 OpenAPI DF-API-KEY로 사용할 수 있습니다. 즉시 안전하게 저장하고 로그에 기록하지 않습니다. |
| content.accountUUID | string | 바인딩된 계정 UUID입니다. 이 진입점에서 생성하면 ""이며, 계정 바인딩 자격 증명을 생성하지 않습니다. |
| content.createdWay | string | 생성 출처이며, 이 진입점에서는 manual입니다. |
| content.businessType | string | 호환 비즈니스 분류입니다. 일반 수동 Key는 빈 문자열입니다. |
| content.isSystem | integer 또는 boolean | 시스템 내장 표시입니다. 일반 수동 Key는 0/false입니다. |
| content.isOwnerRole | integer 또는 boolean | owner Key 여부입니다. 일반 역할로 생성하면 0이고, owner 호환 분기에서는 1입니다. |
| content.remark | string | 비고이며 기본값은 빈 문자열입니다. |
| content.isBurnAfterReading | integer 또는 boolean | 레거시 표시 플래그입니다. 일반 생성 시 0입니다. 이를 근거로 이후 모든 읽기에서 평문이 절대 반환되지 않는다고 추론할 수는 없습니다. |
| content.callCount | integer 또는 null | 누적 호출 횟수입니다. 생성 스냅샷은 데이터베이스 기본값이 채워지기 전에 null일 수 있으며, 로테이션은 기존 통계를 초기화하지 않습니다. |
| content.lastCallAt | integer 또는 null | 최근 호출 Unix 초입니다. 기록이 없으면 일반적으로 -1입니다. 생성 스냅샷은 null일 수 있으며, 로테이션은 초기화하지 않습니다. |
| content.status | integer | 0은 정상입니다. 삭제 후에는 3이며, 생성/로테이션 성공 시 0을 반환합니다. |
| content.creator | string | 생성한 ID의 UUID입니다. |
| content.updator | string | 최근 수정한 ID이며, 생성 시 일반적으로 빈 문자열입니다. |
| content.createAt | integer | 생성 Unix 초입니다. 로테이션 시 최초 생성 시간을 유지합니다. |
| content.updateAt | integer | 최근 업데이트 Unix 초이며, 생성 후 업데이트되지 않으면 -1입니다. |
| content.deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않으면 -1입니다. |
| content.roleInfo | array<object> |
역할 요약 배열입니다. 일반 분기는 조회된 유효 역할이고, owner 분기는 owner만 포함합니다. 명시적으로 []로 생성한 경우 여기서 []일 수 있지만, 인증은 여전히 wsAdmin으로 폴백되므로 이를 근거로 권한이 없다고 판단할 수 없습니다. 역할의 전체 권한 트리를 반환하지 않습니다. |
| content.roleInfo[].uuid | string | 역할 UUID입니다(예: readOnly/wsAdmin/owner 또는 현재 워크스페이스의 사용자 지정 역할 UUID). |
| content.roleInfo[].name | string | 역할 표시 이름입니다. 표시 이름으로 uuid를 대체할 수 없습니다. |
| content.declaration | object | 현재 워크스페이스의 공통 선언입니다. |
{
"code": 200,
"content": {
"id": 101,
"uuid": "wsak_example",
"workspaceUUID": "wksp_example",
"name": "automation_reader",
"ak": "<ROTATED-AK>",
"sk": "<ROTATED-SK>",
"accountUUID": "",
"createdWay": "manual",
"businessType": "",
"isSystem": 0,
"isOwnerRole": 0,
"remark": "仅读自动化",
"isBurnAfterReading": 0,
"callCount": 20,
"lastCallAt": 1785427250,
"status": 0,
"creator": "wsak_caller",
"updator": "wsak_caller",
"createAt": 1785427200,
"updateAt": 1785427300,
"deleteAt": -1,
"roleInfo": [
{
"uuid": "readOnly",
"name": "Read-only"
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 404 | ft.AKNotExistOrDelete | 대상이 존재하지 않음, 워크스페이스 간 요청, 삭제/비활성화됨, 시스템 Key 또는 바인딩 계정 Key가 로테이션 조회 조건에 부합하지 않음 | 지정한 AK가 존재하지 않거나 삭제되었습니다 | 현재 워크스페이스 목록에서 활성 수동 Key를 선택합니다. 바인딩 계정 자격 증명은 해당 계정 절차를 사용합니다. |
| 403 | ft.Forbidden | 관리 권한이 부족하거나 owner가 아닌 주체가 owner Key를 로테이션하려 함 | 작업 권한이 없습니다 | 해당 대상을 관리할 권한이 있는 Key를 사용합니다. |
| 500 | ft.InternalServerError | 데이터베이스 또는 자격 증명 캐시 무효화 실패. 로테이션/삭제가 이미 커밋된 후 오류가 반환될 수 있음 | 내부 오류 | 먼저 다른 유효한 관리 Key로 원래 UUID 및 상태를 읽습니다. 로테이션 응답이 유실되고 기존 Key가 이미 무효화된 경우, 다른 유효한 관리 Key로 다시 로테이션하고 새 자격 증명을 안전하게 수신합니다. 이미 무효화된 기존 Key로 반복 재시도하지 마세요. |