생성¶
POST /api/v1/workspace/accesskey/add
개요¶
현재 워크스페이스에 API Key를 생성하고 읽기/관리 역할을 바인딩합니다.
호출 전 확인 및 사용 단계¶
현재 공간에서 workspace.openAPIKeyManage 권한을 가진 OpenAPI Key를 사용합니다. 라우트 선언에는 freeEdition 버전 제한이 표기되어 있지만 현재 OpenAPI 인증 체인은 해당 버전 검사를 수행하지 않으므로, 버전 자체를 반드시 403이라고 설명할 수 없습니다. 가용성은 배포와 실제 권한에 따라 확인합니다. 리소스 범위는 항상 요청 헤더 Key가 속한 공간에서 가져오며, Body로 공간을 전환할 수 없습니다. owner Key는 현재 ID에 owner가 포함되어야 하며, 인터페이스 관리 권한 자체가 이 검사를 대체하지 않습니다.
먼저 역할 목록에서 필요한 최소 역할을 선택한 다음, 기존의 삭제되지 않은 Key 이름을 확인하고 name, remark, 전체 roleUUIDs를 제출합니다. roleUUIDs를 생략하면 기본값이 ["wsAdmin"]이며 읽기 전용이 아닙니다. 명시적 []는 역할 연관을 작성하지 않을 뿐이며 응답 roleInfo=[]입니다. 현재 인증 체인에 유효한 역할 연관이 없으면 여전히 ["wsAdmin"]으로 폴백하므로, []로 권한이 없는 Key를 생성하거나 권한을 취소할 수 없습니다. 최소 권한이 필요하면 readOnly 또는 검증된 사용자 정의 역할을 명시적으로 바인딩합니다. 일반 분기에서는 각 역할이 현재 공간에서 사용 가능하고 status=0인지 항목별로 검증합니다.
과거 설명에는 owner가 포함되지 않는다고 되어 있지만, 현재 구현에는 owner 호환 분기가 있습니다. 배열에 owner가 포함되면 owner Key만 생성하고 다른 역할은 무시하며, 나머지 요소를 항목별로 검증하지 않습니다. 현재 owner ID가 필요하며, 공간마다 시스템이 아니고 삭제되지 않은 owner Key(비활성 포함)를 하나만 허용합니다. owner를 일반 역할 배열에 섞지 마십시오.
생성 및 로테이션 응답에는 ak/sk 평문이 포함되므로 즉시 통제된 자격 증명 저장소에 기록합니다. OpenAPI 인증 헤더에는 Key 값(예: 반환된 sk)을 사용하고 wsak_ 리소스 UUID를 사용하지 않습니다. 이후 목록/상세 조회는 호출 ID, 대상이 수동/계정 바인딩 여부, 현재 Key 여부에 영향을 받아 마스킹될 수 있습니다. 이후 읽기로 손실된 자격 증명을 복구하려 해서는 안 되며, 현재 서비스 구현을 모든 ID에서 평문이 절대 다시 표시되지 않는다고 설명할 수도 없습니다.
이 작업은 멱등하지 않으며, 중복 이름 오류가 발생해도 기존 Key를 대체하지 않습니다. 데이터베이스 커밋이 성공한 후에만 응답합니다. 오류/네트워크 중단 시에는 먼저 목록을 조회하여 이름과 UUID를 확인한 후 생성 여부를 결정해 중복 자격 증명을 피합니다.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| roleUUIDs[*] | string | 단일 유효 역할 UUID입니다. owner ID만 owner Key를 생성할 수 있으며, 일반 역할 분기에서 알 수 없거나 비활성/삭제되었거나 다른 공간의 역할은 거부됩니다. 예시: readOnly획득 또는 입력 방법: 역할 목록에서 반환된 uuid를 사용하고 name은 사용하지 않습니다. |
|
| name | string | Y | 필수 문자열입니다. 호출자는 비어 있지 않게 해야 하지만 현재 선언은 비어 있음을 강제하지 않습니다. 저장 컬럼은 512자이며 512자를 초과하지 않도록 권장합니다. 공백은 자동으로 제거되지 않습니다. null 허용: False 예시: automation_reader획득 또는 입력 방법: 용도에 따라 이름을 정의하고 API Key 목록에서 동일한 이름이 있는지 확인합니다. |
| remark | string | 선택적 문자열로 최대 512자입니다. 생략하면 비어 있으며 null일 수 없습니다. null 허용: False 최대 길이: 512 예시: 仅读自动化획득 또는 입력 방법: 용도, 담당자, 갱신 방식을 기록하고 자격 증명은 저장하지 않습니다. |
|
| roleUUIDs | array | 선택적 전체 역할 UUID 배열입니다. 생략하면 ["wsAdmin"]입니다. []는 연관을 작성하지 않을 뿐이며 인증은 여전히 wsAdmin으로 폴백하므로 권한 취소에 사용할 수 없습니다. 각 항목은 문자열입니다. null은 지원하지 않습니다. owner가 포함되면 특수 호환 분기로 진입하며 사용 설명을 참조하십시오. null 허용: False 예시: ["readOnly"]획득 또는 입력 방법: 역할 목록의 content.data[].uuid에서 현재 공간에서 사용 가능한 역할을 가져오며, 내장 readOnly/wsAdmin/general도 역할 UUID입니다. |
파라미터 추가 설명¶
이 진입점은 현재 공간의 수동 Key를 생성합니다. 필요한 역할을 명시적으로 설정하며, roleUUIDs를 생략하면 wsAdmin이 사용됩니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/accesskey/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"automation_reader","remark":"仅读自动化","roleUUIDs":["readOnly"]}'
응답¶
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": null,
"uuid": "wsak_example",
"workspaceUUID": "wksp_example",
"name": "automation_reader",
"ak": "<NEW-AK>",
"sk": "<NEW-SK>",
"accountUUID": "",
"createdWay": "manual",
"businessType": "",
"isSystem": 0,
"isOwnerRole": 0,
"remark": "仅读自动化",
"isBurnAfterReading": 0,
"callCount": null,
"lastCallAt": null,
"status": 0,
"creator": "wsak_caller",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"roleInfo": [
{
"uuid": "readOnly",
"name": "Read-only"
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입, 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문 무효 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | 요청 JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 예시에 맞게 JSON 객체를 제공합니다. |
| 400 | ft.AKNameRepeat | 이 공간에 동일한 이름의 시스템이 아니며 삭제되지 않은 Key(비활성 Key 포함)가 이미 존재함 | 이미 동일한 이름의 AK가 존재함 | 목록으로 이미 생성되었는지 확인하고, 새 Key가 반드시 필요하면 고유 이름으로 변경합니다. |
| 400 | ft.AKOnwerRepeat | 요청에 owner가 포함되었지만 공간에 시스템이 아니며 삭제되지 않은 owner Key가 이미 존재함 | 이미 소유자 AK가 존재함 | 기존 owner Key의 통제된 로테이션 절차를 사용하고 중복 생성하지 않습니다. |
| 400 | ft.InvalidRoleUUID | 일반 분기의 특정 역할이 유효하지 않거나 이 공간에 대한 권한이 없거나 비활성/삭제됨 | 유효하지 않은 역할 UUID: {} | 현재 공간 역할 목록에서 유효한 uuid를 다시 선택합니다. |
| 403 | ft.Forbidden | 인터페이스 권한 부족 또는 owner가 아닌 ID가 owner Key를 요청함 | 작업 권한이 없습니다 | 조건에 맞는 관리 Key를 사용하고 최소 권한 역할을 우선 사용합니다. |
| 401 | ft.WKSPNotExistOrReleased | 새로 고침 시 현재 공간이 존재하지 않거나 활성 상태가 아님 | 워크스페이스가 존재하지 않음/또는 이미 해제됨 | 대상 공간이 여전히 활성 상태인지 확인하고 관리 Key를 다른 공간에서 재사용하지 않습니다. |
| 500 | ft.InternalServerError | 데이터베이스 또는 자격 증명 캐시 무효화 실패; 로테이션/삭제가 이미 커밋된 후 오류가 반환될 수 있음 | 내부 오류 | 먼저 다른 유효한 관리 Key로 원래 UUID와 상태를 읽습니다. 로테이션 응답이 유실되고 기존 Key가 이미 무효화된 경우, 다른 유효한 관리 Key로 다시 로테이션하고 새 자격 증명을 안전하게 수신합니다. 이미 무효화된 기존 Key로 반복 재시도하지 마십시오. |