콘텐츠로 이동

멤버 개인 API 키 일괄 활성화/비활성화



POST /api/v1/workspace/member/personal_api_key/enable/modify

개요

멤버가 현재 워크스페이스에서 개인 API 키를 사용하는 기능을 일괄 활성화하거나 비활성화합니다.

호출 전 및 사용 단계

워크스페이스 멤버 목록에서 멤버 UUID를 가져와 비어 있지 않은 accountUUIDs와 0/1 스위치를 제출합니다. 계정은 중복 제거되고 빈 값은 무시되며, 대상은 현재 워크스페이스에서 직접 또는 상속된 역할을 가진 유효한 멤버여야 합니다. owner는 비활성화할 수 없습니다. 멤버 스위치를 저장하고 기존 사용자 및 에이전트 개인 키 레코드를 동기적으로 활성화/비활성화하며 해당 인증 캐시를 정리합니다. 활성화는 키를 생성하거나 반환하지 않으며, 삭제된 키는 이를 근거로 재생성되지 않습니다. 반환된 updated는 이번에 중복 제거된 대상 멤버 수이며, 실제 상태가 변경된 키 수가 아닙니다. 이후 멤버 목록의 enablePersonalAPIKey를 조회하여 스위치를 확인하며, 실제 사용을 위해서는 멤버 역할과 API 권한도 충족해야 합니다. 멤버 관계, 역할, 토큰 및 캐시 등의 처리는 단계별로 저장될 수 있습니다. 예외 또는 시간 초과 후에는 먼저 멤버 및 역할 상태를 읽은 다음 재시도를 결정합니다.

요청 헤더

파라미터 이름 유형 필수 설명
DF-API-KEY string Y 워크스페이스의 OpenAPI 인증 자격 증명입니다.
예: <DF-API-KEY>
획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다.

Body 요청 파라미터

파라미터 이름 유형 필수 설명
accountUUIDs[*] string 배열 내 단일 문자열 식별자입니다.
예: acnt_example
획득 또는 입력 방법: 워크스페이스 멤버 목록의 content.data[].uuid에서 현재 워크스페이스 멤버 계정 UUID를 획득합니다. API Key UUID 또는 이메일이 아닙니다.
accountUUIDs array Y 대상 계정 UUID 배열이며, 동일한 워크스페이스의 실제 멤버를 전달하고 비어 있지 않은 문자열을 사용합니다.
null 허용: False
예: ["acnt_example"]
획득 또는 입력 방법: 워크스페이스 멤버 목록의 content.data[].uuid에서 현재 워크스페이스 멤버 계정 UUID를 획득합니다. API Key UUID 또는 이메일이 아닙니다.
enablePersonalAPIKey integer Y 필수 정수이며 0 또는 1만 허용합니다. JSON 불리언 또는 문자열이 아닙니다.
null 허용: False
선택 가능한 값: [0, 1]
예: 0
획득 또는 입력 방법: 대상 멤버가 이 워크스페이스의 개인 키를 사용하지 못하게 하려면 0, 허용하려면 1을 입력합니다.

파라미터 추가 설명

현재 공개 파라미터 선언의 정수 0/1을 사용합니다. 컨트롤러에서 호환되는 다른 유형은 공개 호출 형식으로 사용하지 않습니다. 이 API는 어떤 키 내용도 반환하지 않습니다.

요청 예시

curl --request POST 'https://openapi.guance.com/api/v1/workspace/member/personal_api_key/enable/modify' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"accountUUIDs":["acnt_example"],"enablePersonalAPIKey":0}'

응답

HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.

필드 유형 설명
content.updated integer 이번에 처리된 중복 제거된 비어 있지 않은 멤버 수입니다.
content.declaration object 또는 null 워크스페이스 공통 선언입니다.
{
  "code": 200,
  "content": {
    "updated": 1,
    "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 객체를 제출하세요.
406 ft.MissingParameters 계정 배열이 비어 있거나 스위치 필드가 누락됨 파라미터 누락 하나 이상의 멤버 UUID를 제출하고 enablePersonalAPIKey를 제공하세요.
404 ft.NotFoundAccount 계정이 존재하지 않거나 상태가 요구 사항을 충족하지 않거나 이 워크스페이스의 유효한 역할을 찾을 수 없음 지정된 계정을 찾을 수 없음 현재 워크스페이스 멤버 목록에서 계정을 다시 가져오고 직접 및 상속된 역할을 확인하세요.
403 ft.Forbidden owner의 개인 API 키를 비활성화하려고 시도함 작업 권한이 없습니다 owner 스위치를 유지하고 다른 멤버를 조정하세요.
500 ft.InternalServerError 데이터 저장, 연결 리소스 또는 캐시 처리 실패 내부 오류 먼저 멤버 및 권한의 현재 상태를 확인한 후 재시도를 결정하세요. 지속적으로 실패하면 traceId와 민감 정보가 마스킹된 요청을 제공하세요.

문서 평가

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