> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.5/basic-tutorials/guides/data/ai-drive/auth-key.md). # AI 드라이브 인증 키 [AI 드라이브](/default/v1.9.5/basic-tutorials/guides/data/ai-drive.md)에 저장한 문서를 **GenOS 밖의 코드에서 검색**할 때 쓰는 키입니다. 코드로 작성한 워크플로우·코드 서빙·MCP 도구처럼 Flowise 화면이 아닌 곳에서 드라이브를 조회하려면 지금까지 관리자 API를 직접 호출해야 했는데, v1.9.5부터는 **드라이브 단위 인증 키**로 대체합니다. 인증 키는 드라이브 내부의 **「인증 키」 탭**에서 관리하며, 키를 쓰려면 먼저 **결재로 사용 허용**을 받아야 합니다. | 역할 | 경로 | | ------------- | ---------------------------------- | | 인증 키 발급·갱신·복사 | 데이터 > AI 드라이브 > 드라이브 내부 > 「인증 키」 탭 | | 사용 허용·해제 신청 | 같은 탭의 「인증 키 사용」 설정 | | 결재 이력 확인 | 같은 탭 하단 「결재 이력」 | | 결재 처리 | 운영 > 결재 | | 활동 내역 확인 | 드라이브 내부 > 「활동」 탭 > 「인증 키」 필터 | > **보안 유의** — 인증 키로는 **보안등급과 무관하게 이 드라이브의 모든 문서를 검색할 수 있습니다.** 그래서 키 자체를 만들기 전에 사용 허용 결재를 거칩니다. ### 주요 개념 | 개념 | 설명 | | -------- | ------------------------------------------------------------------------ | | 인증 키 | 드라이브 문서를 외부 코드에서 조회·검색할 때 쓰는 키입니다. 읽기 전용 키와 쓰기 가능 키 두 종류가 있습니다. | | 인증 키 사용 | 이 드라이브에서 인증 키를 **생성·갱신·복사할 수 있게 하는 설정**입니다. 허용 안 됨 · 결재 대기 · 허용됨 3상태입니다. | | 사용 허용 결재 | 인증 키를 쓰려면 거치는 결재입니다. 신청 사유를 적어 신청하고, 결재자가 승인해야 허용됩니다. | | 사용 해제 | 허용 상태를 되돌리는 것입니다. 승인되면 **이미 발급된 키가 폐기**되어 그 키로 동작하던 호출이 중단됩니다. | | 갱신 | 기존 키를 폐기하고 새 키를 발급하는 작업입니다. 갱신 즉시 이전 키는 쓸 수 없습니다. | ### 인증 키 탭 드라이브 내부의 **「인증 키」** 탭에서 관리합니다. 탭에는 키 카드와 사용처 안내, 그리고 하단에 결재 이력 섹션이 있습니다.

| 카드 | 설명 | | ------- | -------------------------------------------------------- | | 읽기 전용 키 | 문서 조회·검색만 가능한 키입니다. | | 쓰기 가능 키 | 조회·검색에 더해 쓰기가 가능한 키입니다. **드라이브 쓰기 권한이 있는 사용자에게만 표시**됩니다. | 키를 쓰는 곳은 7개 메뉴로 안내됩니다. | 메뉴 | 용도 | | ------ | -------------------------------- | | 코드스페이스 | AI 드라이브 문서 조회 및 검색 | | 코드 서빙 | AI 드라이브 문서 조회 및 검색 시 사용 | | 평가지표 | 평가 내 코드에서 AI 드라이브 문서 조회 | | MCP 도구 | 도구 내 코드에서 AI 드라이브 문서 조회 | | MCP 서버 | 서버 내 스크립트 코드에서 AI 드라이브 문서 조회 | | 워크플로우 | Python 단계 내 AI 드라이브 조회 및 검색 시 사용 | | 전처리기 | AI 드라이브 적재 파이프라인 데이터 읽기 | 탭 안내 문구는 다음과 같습니다. > ※ 인증 키로는 보안등급과 무관하게 이 드라이브의 모든 문서를 검색할 수 있습니다.\ > 인증 키 사용은 결재 승인 후에만 허용됩니다. ### 인증 키 사용 상태 「인증 키 사용」 설정은 3상태이며, 상태에 따라 할 수 있는 일이 달라집니다. | 상태 | 의미 | 생성·갱신·복사 | | ------ | ----------------- | ------------------------------------- | | 허용 안 됨 | 아직 허용되지 않음 | 불가 | | 결재 대기 | 허용 또는 해제 결재가 진행 중 | 불가 (허용 대기 시) / 기존 키는 그대로 동작 (해제 대기 시) | | 허용됨 | 결재 승인 완료 | 가능 | 설정 옆 도움말에는 「이 드라이브의 인증 키를 생성 · 갱신 · 복사할 수 있게 하는 설정입니다.」가 표시됩니다. #### 사용 허용 신청 「허용 안 됨」 상태에서 사용 허용을 신청합니다. **「인증 키 사용 허용 신청」** 모달이 열리며, 다음 안내가 표시됩니다. > 승인 시 이 드라이브의 인증 키를 생성 · 갱신 · 복사할 수 있습니다. 인증 키로는 보안등급과 무관하게 드라이브의 모든 문서를 검색할 수 있습니다. **신청 사유는 필수**입니다(`승인자가 판단할 수 있도록 사용 목적과 적용 범위를 적어 주세요`). 비워 두면 `신청 사유를 입력해 주세요` 가 표시됩니다. \[승인 신청]을 누르면 `승인 신청이 완료되었습니다` 토스트가 뜹니다.

#### 결재 대기 신청 후에는 상태가 `결재 대기`가 되고 배너가 표시됩니다. | 상황 | 배너 | | -------- | --------------------------------------------------------------------------- | | 허용 신청 대기 | **인증 키 사용 허용 결재 대기 중** — 승인 완료 후 적용됩니다. 대기 중에는 인증 키 생성 · 갱신 · 복사가 계속 차단됩니다. | | 해제 신청 대기 | **인증 키 사용 해제 결재 대기 중** — 승인 완료 후 인증 키가 폐기됩니다. 대기 중에는 인증 키가 그대로 동작합니다. |

대기 중에는 설정을 바꿀 수 없습니다(`결재 대기 중에는 변경할 수 없습니다`). 신청을 되돌리려면 \[신청 취소]를 누르고 확인합니다. 이미 결재가 끝난 뒤에 취소를 시도하면 `이미 결재가 완료된 신청입니다. 최신 상태로 갱신했습니다` 가 표시되고 화면이 최신 상태로 갱신됩니다. #### 사용 해제 신청 허용 상태를 되돌릴 때는 **「인증 키 사용 해제 신청」** 모달에서 해제 사유를 적어 신청합니다. > 승인 시 이 드라이브의 인증 키가 폐기되어 해당 키로 동작하던 호출이 중단됩니다. 다시 사용하려면 사용 허용을 재신청해야 합니다. #### 내 드라이브 예외 **내 드라이브는 결재를 거치지 않고 즉시 적용**됩니다. 허용 신청 모달이 뜨지 않고 바로 `인증 키 사용이 허용되었습니다` 로 처리되며, 결재 이력도 남지 않습니다. 결재 이력 섹션에는 「내 드라이브는 결재 없이 즉시 적용돼 결재 이력이 남지 않습니다.」가 표시됩니다. ### 인증 키 발급·갱신·복사 사용이 허용된 뒤에 키를 발급합니다. 발급한 키는 복사해서 코드에 사용합니다.

**갱신**은 기존 키를 폐기하고 새 키를 내주는 작업입니다. 확인 모달에 다음 안내가 표시되고, 계속하려면 안내된 문구를 입력해야 합니다. > 인증 키를 갱신하면 기존 인증 키는 더 이상 사용할 수 없으며, 이 작업은 되돌릴 수 없습니다. 기존 인증 키가 현재 서비스에서 사용 중이지 않은지 반드시 확인해 주세요. | 작업 | 가능한 사용자 | | ------------- | -------------------------------------------------------------------------------------- | | 읽기 전용 키 확인·복사 | 드라이브 읽기 권한이 있는 사용자 | | 쓰기 가능 키 발급·갱신 | 드라이브 **쓰기 권한**이 있는 사용자 | | 사용 허용·해제 신청 | 드라이브 쓰기 권한이 있는 사용자 | | 결재 승인·반려 | `Auth Key Approval` 읽기·쓰기 권한과 해당 드라이브 **쓰기 권한**을 모두 가진 사용자. 드라이브를 만든 사람이라도 이 조건이 필요합니다 | 권한·상황에 따라 버튼이 비활성화되고 사유가 안내됩니다. | 상황 | 안내 | | ------------------- | -------------------------------------------- | | 아직 허용되지 않음 (쓰기 권한자) | 인증 키 사용 허용을 먼저 신청해 주세요 | | 아직 허용되지 않음 (읽기 권한자) | 드라이브 쓰기 권한자에게 인증 키 사용 허용을 요청해 주세요 | | 공유받은 문서함에서 진입 | 공유받은 문서함에서는 발급·갱신할 수 없습니다. 원본 드라이브에서 진행해 주세요 | | 요청 처리 중 | 처리 중입니다. 잠시만 기다려 주세요 | > 이 드라이브가 감싸고 있는 벡터 DB 화면에서는 키를 발급할 수 없습니다. 「이 벡터 DB 의 인증 키는 AI 드라이브에서 관리합니다. 발급·갱신은 해당 드라이브의 인증 키 탭에서 사용 허용을 받은 뒤 진행해 주세요.」 가 안내됩니다. ### 결재 이력 인증 키 탭 하단의 **「결재 이력」** 섹션에서 사용 허용·해제 결재 내역을 확인합니다(부제: 인증 키 사용 허용 · 해제 결재 내역). | 컬럼 | 설명 | | ---------- | ---------------------------- | | ID | 결재 ID입니다. 검색 기준으로도 쓸 수 있습니다. | | 유형 | `허용` 또는 `해제` | | 신청자 / 신청일시 | 신청한 사용자와 일시 | | 결재자 / 결재일시 | 처리한 결재자와 일시 | | 상태 | `대기` · `승인` · `반려` · `신청 취소` | | 반려 사유 | 반려된 경우의 사유 | 아직 신청 이력이 없으면 「인증 키 사용 허용을 신청하면 이력이 표시됩니다.」가 표시됩니다.

#### 결재 상세 행을 열면 신청 내용과 결재 결과를 확인합니다. | 영역 | 내용 | | -------- | -------------------------------------------------------------- | | 신청 내용 | 신청자 / 신청일시, 결재 대상 / 유형(`인증 키` · `수정`), 리소스(`AI 드라이브`) · 리소스 이름 | | 신청 내용 상세 | 항목 `인증 키 사용`, 변경 전 `미사용` → 변경 후 `사용` | | 신청 사유 | 신청 시 입력한 사유 | | 결재 결과 | 결재 상태, 결재자 / 결재일시, 반려 사유 | 변경 후 값에 마우스를 올리면 다음 설명이 표시됩니다. * 허용 — 보안등급과 무관하게 이 리소스에 외부 접근용 인증 키를 발급할 수 있습니다. * 해제 — 이미 발급된 인증 키가 차단됩니다.

#### 승인 목록 연동 결재자는 [**운영 > 결재**](/default/v1.9.5/admin-management/settings/approval.md) 의 승인 목록에서도 같은 건을 처리합니다. 목록에는 결재 대상이 드라이브 이름으로, 유형이 `인증 키` 로 표시됩니다. 승인 목록에는 **해당 드라이브 읽기 권한이 있는 결재자에게만** 노출되며, 승인·반려하려면 드라이브 **쓰기 권한**도 있어야 합니다. 읽기 권한만 있으면 목록에 보여도 처리할 수 없습니다.

### 활동 내역 드라이브 내부 「활동」 탭에서 **결재를 거치지 않은** 인증 키 활동을 확인합니다. **「인증 키」 필터**로 좁혀 볼 수 있습니다. | 활동 | 기록되는 경우 | | ---------- | ------------------ | | 인증 키 생성 | 키를 발급했을 때 | | 인증 키 갱신 | 키를 갱신했을 때 | | 인증 키 사용 허용 | 내 드라이브에서 바로 허용했을 때 | | 인증 키 사용 해제 | 내 드라이브에서 바로 해제했을 때 | 그룹 드라이브처럼 결재를 거친 신청·승인·반려는 활동 탭에 나오지 않습니다. 이 기록은 「인증 키」 탭 하단 「결재 이력」에서 확인합니다.

### API 호출 방식 인증 키 탭의 **\[API 호출]** 버튼을 누르면 「AI 드라이브 API 사용」 가이드 모달이 열립니다. | 항목 | 내용 | | -------- | ------------------------------------------------------- | | 기본 엔드포인트 | 드라이브 경로 + Weaviate API 경로(`v1/graphql`, `v1/objects` 등) | | 식별자 | **AI 드라이브 ID** — URL 경로에 사용 | | 컬렉션 ID | 실제 Weaviate 컬렉션(클래스) 이름 — **GraphQL 쿼리 본문**에 사용 | | 인증 | 모든 요청에 `Authorization` 헤더로 인증 키 전달 | | 호출 예시 | Python 키워드 검색 · Python 하이브리드 검색 · curl 키워드 검색 |

> 컬렉션 ID 는 URL 경로에 쓰는 ID 와 **다른 값**이므로 서로 바꿔 쓰지 마세요. > 기본 예시는 임베딩이 필요 없는 키워드 검색(bm25)입니다. 컬렉션은 `vectorizer: none`(BYOV)으로 만들어지므로 hybrid 에 쿼리 텍스트만 넘기는 호출은 동작하지 않습니다. 벡터 검색은 임베딩 서빙으로 벡터를 직접 만들어 넣는 하이브리드 예시를 사용하세요. 모달에도 「이 인증 키로는 보안등급과 무관하게 이 드라이브의 모든 문서를 검색할 수 있습니다.」 경고가 함께 표시됩니다. ### 오류·예외 처리 | 상황 | 표시 문구 | | ------------------ | ----------------------------------- | | 신청 사유 미입력 | 신청 사유를 입력해 주세요 | | 이미 진행 중인 결재가 있음 | 이미 진행 중인 결재가 있습니다 | | 허용 신청 실패 | 인증 키 사용 허용 신청에 실패 하였습니다. 다시 시도해 주세요 | | 신청 취소 실패 | 신청 취소에 실패 하였습니다. 다시 시도해 주세요 | | 해제 실패 | 인증 키 사용 해제에 실패 하였습니다. 다시 시도해 주세요 | | 이미 결재 완료된 신청 취소 시도 | 이미 결재가 완료된 신청입니다. 최신 상태로 갱신했습니다 | | 키 생성 실패 | 인증 키 생성에 실패 하였습니다. 다시 시도해 주세요 | | 키 갱신 실패 | 인증 키 갱신에 실패 하였습니다. 다시 시도해 주세요 | 성공 시에는 `{이름}를 생성했습니다.` · `{이름}를 갱신했습니다. 이전 키는 더 이상 쓸 수 없습니다.` · `인증 키 사용이 해제 되었습니다` 등의 토스트가 표시됩니다. ### 사용자 시나리오 #### 코드로 만든 워크플로우에서 드라이브를 검색하고 싶은 경우 드라이브의 인증 키 탭에서 사용 허용을 신청하고, 승인되면 키를 발급해 복사합니다. \[API 호출] 가이드의 엔드포인트·헤더·예시를 그대로 코드에 옮겨 씁니다. #### 키를 발급하려는데 버튼이 눌리지 않는 경우 상태가 `허용 안 됨` 입니다. 쓰기 권한자라면 사용 허용을 먼저 신청하고, 읽기 권한자라면 드라이브 쓰기 권한자에게 요청합니다. #### 공유받은 드라이브에서 키가 발급되지 않는 경우 공유받은 문서함에서는 발급·갱신을 할 수 없습니다. 원본 드라이브에서 진행합니다. #### 키가 유출된 것 같은 경우 \[갱신]으로 즉시 새 키를 발급합니다. 이전 키는 갱신 즉시 무효가 되므로, 그 키를 쓰던 서비스의 설정을 함께 바꿔야 합니다. #### 더 이상 외부 호출을 쓰지 않는 경우 사용 해제를 신청합니다. 승인되면 발급된 키가 폐기되고 그 키로 동작하던 호출이 중단되므로, 사용 중인 서비스가 없는지 먼저 확인합니다. #### 내 드라이브에서 신청 모달이 뜨지 않는 경우 내 드라이브는 결재 없이 즉시 적용되는 것이 정상입니다. 결재 이력도 남지 않습니다. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://genos-docs.gitbook.io/default/v1.9.5/basic-tutorials/guides/data/ai-drive/auth-key.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.