Source: https://ailoot.ai/docs/ko/cabinet/keys/ Canonical: https://ailoot.ai/docs/ko/cabinet/keys/ Language: ko [대시보드 API](https://ailoot.ai/docs/ko/) # API 키 [Markdown](https://ailoot.ai/docs/ko/cabinet/keys/index.md) 메서드, 요청 필드 및 응답입니다. 이 섹션에는 메서드가 5개 있습니다. 메서드를 열어 접근 조건, 요청 필드 및 응답을 확인하세요. | 메서드와 경로 | 설명 | 접근 | | --- | --- | --- | | `GET /api/v1/keys` | 목록 — API 키 | 대시보드 토큰 | | `POST /api/v1/keys` | API 키 생성 | 대시보드 토큰 | | `DELETE /api/v1/keys/:id` | 삭제 — API 키 | 대시보드 토큰 | | `GET /api/v1/keys/:id` | 식별자로 조회 — API 키 | 대시보드 토큰 | | `PUT /api/v1/keys/:id` | API 키 수정 | 대시보드 토큰 | **GET /api/v1/keys** — 목록 — API 키 접근: 대시보드 토큰 GET`/api/v1/keys` 읽기 작업입니다. ID는 이전 응답에서 가져옵니다 ```bash curl --fail-with-body "https://ailoot.ai/api/v1/keys" \ -H "Authorization: Bearer $TOKEN" ``` ## 쿼리 매개변수 | 필드 | 타입 | 필수 | 검증 / 설명 | | --- | --- | --- | --- | | `sort_by` | `string` | 아니요 | ; 기본값: created\_at | | `sort_order` | `string` | 아니요 | ; 기본값: desc | | `search` | `string` | 아니요 | | | `status` | `string` | 아니요 | | | `page` | `integer` | 아니요 | ; 기본값: 1; positive; page\_size/limit \<=1000 | | `page_size` | `integer` | 아니요 | ; 기본값: 20; positive; page\_size/limit \<=1000 | | `limit` | `integer` | 아니요 | ; 기본값: 20; positive; page\_size/limit \<=1000 | 요청 본문은 필요하지 않습니다. 위 매개변수를 URL에 전달하세요. ## 응답 JSON 응답에는 code, message, data가 포함됩니다. data 내용은 아래 스키마를 참고하세요. 응답 데이터 스키마: `APIKey`. 필드와 유형은 «데이터 스키마» 페이지에서 확인하세요. 응답 스키마, 예시 값 ```json { "code": 0, "message": "success", "data": { "items": [ { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } ], "total": "PLACEHOLDER_TOTAL (integer)", "page": "PLACEHOLDER_PAGE (integer)", "page_size": "PLACEHOLDER_PAGE_SIZE (integer)", "pages": "PLACEHOLDER_PAGES (integer)" } } ``` 특이 사항: 모든 개인정보와 객체는 JWT의 주체로 범위가 제한됩니다. 특이 사항: 응답에 비밀 값 key가 포함됩니다. 실제 값을 공개하지 마세요. **POST /api/v1/keys** — API 키 생성 접근: 대시보드 토큰 POST`/api/v1/keys` ## JSON / 폼 필드 | 필드 | 타입 | 필수 | 검증 / 설명 | | --- | --- | --- | --- | | `name` | `string` | 예 | required | | `custom_key` | `string` | 아니요 | ; 선택 사항인 사용자 지정 키 값. null 가능 | | `ip_whitelist` | `array` | 아니요 | ; 허용 IP 목록 | | `ip_blacklist` | `array` | 아니요 | ; 차단 IP 목록 | | `quota` | `number` | 아니요 | ; 키의 USD 지출 한도. null 가능 | | `expires_in_days` | `integer` | 아니요 | ; 유효기간(일). null 가능 | | `rate_limit_5h` | `number` | 아니요 | ; null 가능 | | `rate_limit_1d` | `number` | 아니요 | ; null 가능 | | `rate_limit_7d` | `number` | 아니요 | ; null 가능 | 요청 본문 템플릿 ```json { "name": "PLACEHOLDER_NAME (string)", "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "quota": "PLACEHOLDER_QUOTA (number)", "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)" } ``` PLACEHOLDER는 사용자의 입력과 그 타입을 나타냅니다. 값을 바꾸고 필요한 선택 필드만 남기세요. 숫자, boolean, 객체 또는 배열 대신 문자열 표식을 보내면 안 됩니다. 요청 스키마: `CreateAPIKeyRequest` ## 응답 JSON 응답에는 code, message, data가 포함됩니다. data 내용은 아래 스키마를 참고하세요. 응답 데이터 스키마: `APIKey`. 필드와 유형은 «데이터 스키마» 페이지에서 확인하세요. 응답 스키마, 예시 값 ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } } ``` 특이 사항: 모든 개인정보와 객체는 JWT의 주체로 범위가 제한됩니다. 특이 사항: 상태를 변경하거나 일회성 인증을 이어가는 작업입니다. 예제는 규약을 설명하며 실행되지 않습니다. 특이 사항: Idempotency-Key를 지원합니다. 재전송하면 저장된 응답과 X-Idempotency-Replayed를 반환합니다. 특이 사항: 응답에 비밀 값 key가 포함됩니다. 실제 값을 공개하지 마세요. 이 메서드는 데이터를 변경합니다. Idempotency-Key를 명시한 메서드만 재전송이 안전합니다. 응답을 잃었다면 먼저 결과(예: 키 목록)를 확인한 뒤 재전송 여부를 결정하세요. **DELETE /api/v1/keys/:id** — 삭제 — API 키 접근: 대시보드 토큰 DELETE`/api/v1/keys/:id` ## 경로 매개변수 | 필드 | 타입 | 필수 | 검증 / 설명 | | --- | --- | --- | --- | | `id` | `integer` | 예 | | 요청 본문은 필요하지 않습니다. ## 응답 JSON 응답에는 code, message, data가 포함됩니다. data 내용은 아래 스키마를 참고하세요. 응답 스키마, 예시 값 ```json { "code": 0, "message": "success", "data": { "message": "VALUE_FROM_RESPONSE" } } ``` 특이 사항: 모든 개인정보와 객체는 JWT의 주체로 범위가 제한됩니다. 특이 사항: 상태를 변경하거나 일회성 인증을 이어가는 작업입니다. 예제는 규약을 설명하며 실행되지 않습니다. 특이 사항: 응답에 비밀 값 key가 포함됩니다. 실제 값을 공개하지 마세요. 이 메서드는 데이터를 변경합니다. Idempotency-Key를 명시한 메서드만 재전송이 안전합니다. 응답을 잃었다면 먼저 결과(예: 키 목록)를 확인한 뒤 재전송 여부를 결정하세요. **GET /api/v1/keys/:id** — 식별자로 조회 — API 키 접근: 대시보드 토큰 GET`/api/v1/keys/:id` 읽기 작업입니다. ID는 이전 응답에서 가져옵니다 ```bash curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \ -H "Authorization: Bearer $TOKEN" ``` ## 경로 매개변수 | 필드 | 타입 | 필수 | 검증 / 설명 | | --- | --- | --- | --- | | `id` | `integer` | 예 | | 요청 본문은 필요하지 않습니다. 위 매개변수를 URL에 전달하세요. ## 응답 JSON 응답에는 code, message, data가 포함됩니다. data 내용은 아래 스키마를 참고하세요. 응답 데이터 스키마: `APIKey`. 필드와 유형은 «데이터 스키마» 페이지에서 확인하세요. 응답 스키마, 예시 값 ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } } ``` 특이 사항: 모든 개인정보와 객체는 JWT의 주체로 범위가 제한됩니다. 특이 사항: 응답에 비밀 값 key가 포함됩니다. 실제 값을 공개하지 마세요. **PUT /api/v1/keys/:id** — API 키 수정 접근: 대시보드 토큰 PUT`/api/v1/keys/:id` ## 경로 매개변수 | 필드 | 타입 | 필수 | 검증 / 설명 | | --- | --- | --- | --- | | `id` | `integer` | 예 | | ## JSON / 폼 필드 | 필드 | 타입 | 필수 | 검증 / 설명 | | --- | --- | --- | --- | | `name` | `string` | 아니요 | | | `status` | `string` | 아니요 | omitempty,oneof=active inactive | | `ip_whitelist` | `array` | 아니요 | ; 허용 IP: null은 목록을 변경하지 않고 빈 배열은 목록을 비웁니다. null 가능 | | `ip_blacklist` | `array` | 아니요 | ; 차단 IP: null은 목록을 변경하지 않고 빈 배열은 목록을 비웁니다. null 가능 | | `quota` | `number` | 아니요 | ; 키의 USD 지출 한도. 0은 무제한. null 가능 | | `expires_at` | `string` | 아니요 | ; ISO 8601 형식의 만료 시각. null 가능 | | `reset_quota` | `boolean` | 아니요 | ; 지출 한도에서 사용한 금액 초기화. null 가능 | | `rate_limit_5h` | `number` | 아니요 | ; null 가능 | | `rate_limit_1d` | `number` | 아니요 | ; null 가능 | | `rate_limit_7d` | `number` | 아니요 | ; null 가능 | | `reset_rate_limit_usage` | `boolean` | 아니요 | ; 시간 창별 한도에 누적된 지출 초기화. null 가능 | 요청 본문 템플릿 ```json { "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "quota": "PLACEHOLDER_QUOTA (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)" } ``` PLACEHOLDER는 사용자의 입력과 그 타입을 나타냅니다. 값을 바꾸고 필요한 선택 필드만 남기세요. 숫자, boolean, 객체 또는 배열 대신 문자열 표식을 보내면 안 됩니다. 요청 스키마: `UpdateAPIKeyRequest` ## 응답 JSON 응답에는 code, message, data가 포함됩니다. data 내용은 아래 스키마를 참고하세요. 응답 데이터 스키마: `APIKey`. 필드와 유형은 «데이터 스키마» 페이지에서 확인하세요. 응답 스키마, 예시 값 ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } } ``` 특이 사항: 모든 개인정보와 객체는 JWT의 주체로 범위가 제한됩니다. 특이 사항: 상태를 변경하거나 일회성 인증을 이어가는 작업입니다. 예제는 규약을 설명하며 실행되지 않습니다. 특이 사항: 응답에 비밀 값 key가 포함됩니다. 실제 값을 공개하지 마세요. 특이 사항: 키에 예약 금액이 있는 진행 중 요청이 있으면 지출 한도를 낮추거나 초기화할 수 없습니다. 변경할 필드만 전송하세요. 이 메서드는 데이터를 변경합니다. Idempotency-Key를 명시한 메서드만 재전송이 안전합니다. 응답을 잃었다면 먼저 결과(예: 키 목록)를 확인한 뒤 재전송 여부를 결정하세요. 궁금한 점이 남았나요? Request ID와 설명을 보내 주시면 해결을 도와드리겠습니다.[지원팀에 문의](mailto:support@ailoot.ai) ## Ailoot · 회사와 그 프로젝트 포트폴리오 Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다. 회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출. Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.