API 키

메서드, 요청 필드 및 응답입니다.

전체 가이드

이 섹션에는 메서드가 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는 이전 응답에서 가져옵니다

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. 필드와 유형은 «데이터 스키마» 페이지에서 확인하세요.

응답 스키마, 예시 값

{
  "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 가능

요청 본문 템플릿

{
  "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. 필드와 유형은 «데이터 스키마» 페이지에서 확인하세요.

응답 스키마, 예시 값

{
  "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가 포함됩니다. 실제 값을 공개하지 마세요.

DELETE /api/v1/keys/:id — 삭제 — API 키

접근: 대시보드 토큰

DELETE/api/v1/keys/:id

경로 매개변수

필드	타입	필수	검증 / 설명
`id`	`integer`	예

요청 본문은 필요하지 않습니다.

응답

JSON 응답에는 code, message, data가 포함됩니다. data 내용은 아래 스키마를 참고하세요.

응답 스키마, 예시 값

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}

특이 사항: 모든 개인정보와 객체는 JWT의 주체로 범위가 제한됩니다.

특이 사항: 상태를 변경하거나 일회성 인증을 이어가는 작업입니다. 예제는 규약을 설명하며 실행되지 않습니다.

특이 사항: 응답에 비밀 값 key가 포함됩니다. 실제 값을 공개하지 마세요.

GET /api/v1/keys/:id — 식별자로 조회 — API 키

접근: 대시보드 토큰

GET/api/v1/keys/:id

읽기 작업입니다. ID는 이전 응답에서 가져옵니다

curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"

경로 매개변수

필드	타입	필수	검증 / 설명
`id`	`integer`	예

요청 본문은 필요하지 않습니다. 위 매개변수를 URL에 전달하세요.

응답

JSON 응답에는 code, message, data가 포함됩니다. data 내용은 아래 스키마를 참고하세요.

응답 데이터 스키마: APIKey. 필드와 유형은 «데이터 스키마» 페이지에서 확인하세요.

응답 스키마, 예시 값

{
  "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 가능

요청 본문 템플릿

{
  "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)"
}

요청 스키마: UpdateAPIKeyRequest

응답

JSON 응답에는 code, message, data가 포함됩니다. data 내용은 아래 스키마를 참고하세요.

응답 데이터 스키마: APIKey. 필드와 유형은 «데이터 스키마» 페이지에서 확인하세요.

응답 스키마, 예시 값

{
  "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가 포함됩니다. 실제 값을 공개하지 마세요.

특이 사항: 키에 예약 금액이 있는 진행 중 요청이 있으면 지출 한도를 낮추거나 초기화할 수 없습니다. 변경할 필드만 전송하세요.

궁금한 점이 남았나요? Request ID와 설명을 보내 주시면 해결을 도와드리겠습니다.지원팀에 문의