콘텐츠로 이동

생성



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로 반복 재시도하지 마십시오.

문서 평가

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