# API 키 관리 화면의 모든 것

> Source: https://docs.wrks.ai/admin-help/integrations/api-keys · Last updated: 2026-11-05

**`관리자 > API 키 관리` 에서 회사 시스템이 웍스AI를 부를 때 쓰는 키를 발급합니다.**

### API 키가 뭔가요

**사람이 아니라 시스템이 웍스AI를 쓸 때 필요한 열쇠예요.** 사내 프로그램에서 자동으로 문서를 요약하거나 번역하게 할 때 씁니다.

직원이 화면에서 쓰는 것과는 별개예요. 일반 사용에는 필요 없습니다.

### 화면에 있는 것

| 항목           | 무엇을 하나                                              |
| ------------ | --------------------------------------------------- |
| `+ 새 키 발급`   | 키 만들기. 키 목록 위 파란 버튼이에요 (키가 하나도 없을 때는 빈 화면 가운데에 있어요) |
| 이름           | 어디에 쓰는 키인지 (예: production-system-key)               |
| 만료 기간        | `30일` / `90일` / `1년` / `직접 입력` (기본값은 `1년`)          |
| 생성일 / 만료일    | 언제 만들고 언제 끝나는지                                      |
| 상태          | `활성` / `곧 만료`(만료 21일 전부터, 마우스를 올리면 `D-N일`) / `만료` |
| 허용 IP        | 키마다 어디서 쓸 수 있는지. 칸 옆 `변경하기` 로 바꿔요                    |
| 허용된 IP 주소 관리 | 회사 목록. 따로 정하지 않은 키는 모두 이 목록을 따라요                      |
| `API 문서`     | 연동 방법을 적은 문서 열기 (화면 오른쪽 위)                          |

### 발급하는 방법

1. **`+ 새 키 발급`** 을 누르면 **새 API 키 발급** 창이 열려요
2. **이름**(50자까지)을 적고 **만료 기간**을 고릅니다. `직접 입력` 을 고르면 아래에 날짜 칸이 나와요
3. **`발급하기`** 를 누릅니다
4. **`발급 완료`** 창에 키가 보여요. **`복사`** 한 뒤 **`복사 완료, 닫기`** 를 누릅니다

### 발급할 때 주의할 것

**발급 직후 화면에서만 키를 볼 수 있어요.** 창을 닫으면 다시 볼 수 없습니다. 꼭 복사해서 안전한 곳에 보관해 주세요.

이름은 나중에 알아볼 수 있게 지으세요. 키가 여러 개면 어떤 시스템 것인지 구분이 안 됩니다.

### 만료 기간

`30일` / `90일` / `1년` 중에 고르거나 `직접 입력` 으로 날짜를 정합니다.

**짧게 잡는 게 안전합니다.** 키가 유출돼도 자동으로 못 쓰게 되니까요. 다만 만료되면 그 키를 쓰는 시스템이 멈추니 미리 새 키로 바꿔주셔야 해요.

> **직접 정하실 때는 내일부터 5년 안쪽으로만 됩니다.** 달력에서는 내일부터 5년 안쪽 날짜만 고를 수 있어요.

만료 21일 전부터 `곧 만료` 로 표시돼요. 만료된 키는 `만료` 로 바뀌고 회색으로 보여요.

### 허용 IP 제한

`허용된 IP 주소 관리` 에서 **회사의 API 키를 어느 IP에서만 쓸 수 있는지** 정합니다. 이 목록은 회사 목록이에요. **키마다 따로 정하지 않으면 모든 키가 이 목록을 따라요.** 키가 유출돼도 등록한 IP 밖에서는 못 씁니다.

키마다 다르게 하려면 키 목록의 `허용 IP` 칸에서 `변경하기` 를 눌러요. 아래 '키마다 허용 IP를 다르게 정할 수 있나요?' 를 봐 주세요.

**목록이 비어 있으면(`허용된 IP가 없습니다.`) 회사 목록을 따르는 키는 IP 제한 없이 호출돼요.** 하나라도 등록하면 그때부터 등록한 IP 밖에서 오는 호출은 막혀요. 키를 쓰는 시스템의 IP를 등록해 두시길 권해요.

**공인 IP만 등록할 수 있어요.** 세 가지 형식을 지원합니다.

| 형식    | 예시                              |
| ----- | ------------------------------- |
| 단일 IP | `218.144.97.227`                |
| 범위    | `218.144.97.227-218.144.97.230` |
| CIDR  | `218.144.97.224/29`             |

여러 개는 **콤마(,)로 구분**해서 넣습니다.

저장할 때 `API Key 허용 IP 관리` 확인 창에 "이 IP 외에는 API Key 호출이 차단됩니다. 계속하시겠습니까?" 가 떠요. **`적용하기`** 를 누르면 저장돼요.

등록한 IP는 칩 옆 X로 하나씩, `전체 삭제` 로 한꺼번에 지울 수 있어요. 지울 때도 같은 확인 창이 떠요.

> API 키 허용 IP는 **따로 요금이 붙지 않아요.** 하루 요금이 붙는 건 `내부 통제` 의 접속 통제예요.

***

### 자주 묻는 질문

**Q. 키를 잃어버렸어요. 다시 볼 수 있나요?**

없습니다. 발급 직후에만 보여요. 새로 발급받고 예전 키는 삭제해 주세요.

**Q. 키를 삭제하면 어떻게 되나요?**

그 키를 쓰는 시스템이 바로 멈춥니다. 삭제 전에 새 키로 바꿔두세요.

**Q. API 키로 쓴 사용량은 어디에 나오나요?**

`관리자 > 이용 현황` 의 사용자 목록에서 **부가서비스/API** 로 모여 보입니다. → [사용자 목록에 있는 '부가서비스/API'는 무엇인가요](https://docs.wrks.ai/admin-help/billing/addon-api-usage)

**Q. 키마다 사용량을 따로 볼 수 있나요?**

지금은 하나로 합쳐서 보입니다.

**Q. 만료된 키는 어떻게 하나요?**

새로 발급받아 시스템에 넣고, 예전 키는 삭제해 주세요.

**Q. 이미 발급한 키의 만료일을 늘릴 수 있나요?**

없어요. 발급한 키의 만료일은 바꾸거나 연장할 수 없습니다. 만료 전에 **새 키를 발급해 시스템에 넣고**, 예전 키는 삭제해 주세요.

**Q. 만료일 당일 언제부터 막히나요?**

고른 날짜의 오전 9시(한국 시간)에 만료돼요. 그 전에 새 키로 바꿔 두세요.

**Q. 키마다 쓸 수 있는 기능이나 범위를 제한할 수 있나요?**

없어요. 키를 발급할 때 정하는 건 **이름**과 **만료 기간** 두 가지뿐이에요. 키별로 기능·범위를 나누는 설정은 없어요. 허용 IP만 키마다 따로 정할 수 있어요.

**Q. 키마다 허용 IP를 다르게 정할 수 있나요?**

네. 키 목록의 `허용 IP` 칸에서 `변경하기` 를 누르면 `이 키를 어디서 쓸 수 있게 할까요?` 창이 열려요. 셋 중 하나를 골라 `저장하기` 를 눌러 주세요.

| 고르는 것            | 화면 안내                                                                     | 표 칸 표시            |
| ---------------- | ------------------------------------------------------------------------- | ----------------- |
| `회사 설정 따르기`      | 아래 '허용된 IP 주소 관리'에 등록한 회사 목록을 그대로 써요. 회사 목록이 비어 있으면 어디서나 쓸 수 있어요. | `회사 설정 따름`        |
| `이 키만 따로 정하기`    | 여기 적은 IP에서만 이 키를 쓸 수 있어요. 회사 목록은 이 키에 적용되지 않아요.                    | `이 키만 따로 (N개)`    |
| `어디서나 쓸 수 있게 하기` | IP를 확인하지 않아요. IP가 자주 바뀌는 사내 시스템처럼 꼭 필요한 키에만 쓰세요.                   | `어디서나`            |

`이 키만 따로 정하기` 는 IP를 적고 `+ 추가` 를 눌러야 목록에 들어가요. 그냥 저장하면 `'+ 추가'를 눌러 IP를 목록에 넣어 주세요.` 가 떠요. IP는 키마다 최대 100개까지 넣을 수 있어요.

**Q. 허용 IP를 하나도 등록하지 않으면 어떻게 되나요?**

`회사 설정 따름` 인 키는 IP 제한 없이 호출돼요. 등록하면 그때부터 등록한 IP 밖의 호출이 막혀요. 키가 유출됐을 때를 대비해 키를 쓰는 시스템의 IP를 등록해 두시길 권해요.

**Q. "잘못된 IP 형식이 포함되어 있습니다" 라고 나와요.**

사설 IP(`192.168.` 로 시작하는 것 등)는 등록할 수 없어요. 회사 공인 IP를 전산 담당자에게 확인해 주세요.

**Q. 우리 회사 공인 IP를 모르겠어요.**

전산 담당자에게 문의해 주세요. 웍스AI에서는 알려드릴 수 없습니다.

**Q. 직원 로그인 IP 제한과 같은 건가요?**

다릅니다.

* **API 키 허용 IP** — 시스템이 키로 부를 때
* **내부 통제의 IP 주소 관리** — 직원이 로그인할 때

→ [내부 통제 화면의 모든 설정](https://docs.wrks.ai/admin-help/security/internal-control)

**Q. '새 키 발급' 버튼이 어디 있나요?**

키 목록 위의 파란 **`+ 새 키 발급`** 버튼이에요. 키가 하나도 없으면 빈 화면 가운데에 같은 버튼이 보여요.

**Q. 만료일을 직접 고르려면요?**

만료 기간에서 **`직접 입력`** 을 고르면 날짜 칸이 나와요. 날짜를 고르고 **`발급하기`** 를 누르세요. 내일부터 5년 안쪽 날짜만 돼요.

**Q. 키를 여러 개 만들어도 되나요?**

시스템마다 따로 만드시는 걸 권합니다. 문제가 생겼을 때 그 키만 지우면 되니까요.

**Q. API로 파일을 올리면 거절돼요.**

API로 올리는 파일에도 **화면에서 올릴 때와 같은 회사 규칙**이 적용돼요. 회사에서 **업로드 전 결재**를 쓰고 있으면 API로도 파일을 바로 올릴 수 없어요. → [웍스 드라이브 — 관리자가 알아야 할 것](https://docs.wrks.ai/admin-help/features/drive)

**Q. API 사용법 문서가 있나요?**

있어요. `관리자 > API 키 관리` 화면 **오른쪽 위 `API 문서`** 버튼을 누르면 열려요. 부서 관리·사용자 관리 같은 기업 관리 API와 구축 가이드가 들어 있어요. 문서를 보고도 연동이 어려우면 고객지원으로 문의해 주세요.

**Q. 사용자별 한도나 사용량을 API로 조회할 수 있나요?**

**사용자별 월 이용 한도**는 `API 문서` 의 사용자 관리 항목에 안내된 API로 조회하고 바꿀 수 있어요. **사용자별 사용량**을 조회하는 API는 문서에 안내되어 있지 않아요. 사용량은 `관리자 > 이용 현황` · `이용 통계` 화면에서 확인해 주세요.

### 이럴 땐 문의해 주세요

* `API 문서` 를 보고도 연동 방법을 모르겠을 때
* 키가 유출된 것 같을 때 (바로 삭제 후 문의)