Lovable한국어 문서

Lovable API용 워크스페이스 API 키를 만들고, 스코프와 만료일, 크레딧 한도를 설정하고, 승인된 IP 주소로 제한하며 안전하게 관리하는 방법을 알아봅니다.

API 키 만들기 및 관리

Lovable API용 워크스페이스 API 키(access token)를 만들고, 스코프를 지정하고, 취소하며, 키별 크레딧 한도를 설정하고, 키를 승인된 IP 주소로 제한합니다.

워크스페이스 API 키는 Lovable API에 보내는 요청을 인증합니다. 키는 API keys & OAuth 설정 페이지의 Workspace access tokens에서 관리합니다. Lovable로 만든 앱이 API를 호출하게 해 주는 Lovable API 커넥터를 설정할 때도 API 키를 사용합니다. 각 키는 하나의 워크스페이스에 속하며 해당 워크스페이스의 프로젝트와 데이터에만 접근할 수 있습니다. 공개 API는 기존 프로젝트를 관리하고 배포합니다. 배포 빌드를 포함한 현재 엔드포인트는 AI 빌드 크레딧을 사용하지 않습니다.

키를 만들고 관리하려면 Business 또는 Enterprise 플랜과 워크스페이스 owner 또는 admin 역할이 필요합니다.

Free 및 Pro 워크스페이스에서는 워크스페이스 API 키 항목에 업그레이드 안내가 표시됩니다. OAuth 클라이언트는 모든 플랜의 워크스페이스 owner와 admin이 사용할 수 있지만, 민감한 스코프에는 Business 또는 Enterprise 플랜이 필요합니다.

워크스페이스 API 키를 사용하는 이유

팀 워크스페이스를 관리하는 스크립트나 서비스에는 키를 사용하세요. 통합마다 별도의 키를 발급하면 통합별로 접근 권한을 제한하고 개별적으로 취소할 수 있습니다. 키를 사용한 작업은 해당 키를 만든 사람이 수행한 것으로 기록됩니다.

자체 앱을 Lovable에 연결하려면 OAuth 클라이언트를 등록하세요. 그러면 각 사용자가 앱이 요청한 스코프를 검토하고 인가합니다.

일반적인 사용 사례

워크스페이스 API 키는 다음과 같은 관리 작업에 사용합니다.

사용 사례예시
프로젝트 현황 보고기존 프로젝트 목록을 보여 주고 분석 데이터를 읽는 내부 대시보드
게시 자동화기존 프로젝트를 게시하는 워크플로
워크스페이스 보안 모니터링보안 스캔과 워크스페이스 인사이트를 읽는 보고 도구

사전 요구 사항

키를 만들기 전에 다음을 갖추었는지 확인하세요.

  • Business 또는 Enterprise 워크스페이스와 owner 또는 admin 역할
  • HTTPS 요청을 보내고 자격 증명을 안전하게 저장할 수 있는 통합
  • IP 주소를 제한한다면 통합의 공개 아웃바운드 IP 주소 또는 주소 범위

API 키 만들기

각 키에는 고유한 이름, 스코프, 만료일, 선택적 지출 한도, 선택적 IP allowlist가 있습니다. 따라서 통합마다 별도의 키를 발급하세요.

Workspace access tokens 열기

통합이 관리할 워크스페이스를 선택합니다. Workspace settings → API keys & OAuth → Workspace access tokens로 이동한 뒤 New API key를 클릭합니다.

키 이름 지정

나중에 키를 알아볼 수 있도록 Key name을 입력합니다. 예를 들어 CI/CD pipeline 또는 Zapier처럼 입력할 수 있습니다. 이 이름은 워크스페이스 admin과 owner에게 표시됩니다.

크레딧 한도 설정(선택 사항)

이 키로 인증된 요청이 매월 사용할 수 있는 AI 빌드 크레딧을 제한하려면 Credit limit을 설정합니다. 한도는 매월 1일 00:00 UTC에 초기화됩니다. 제한하지 않으려면 비워 둡니다.

만료일 선택

Expiration을 선택합니다. 7일, 30일, 60일, 90일, 180일, 1년 또는 Never 중에서 고를 수 있습니다. 오래 유지되는 서비스 통합에는 "Never"가 동작하지만, 키를 정기적으로 교체하는 편이 더 안전합니다.

접근 권한 부여

Access에서 각 리소스에 대해 None, Read, Read & write 중 하나를 선택합니다. 최소 하나는 부여해야 합니다.

  • Projects: 이 워크스페이스에서 프로젝트 설정 읽기·수정, 프로젝트 삭제, 프로젝트 게시, 프로젝트 보안 스캔 읽기 권한입니다.
  • Workspace: 프로젝트 목록, 워크스페이스 세부 정보, 멤버, 그룹, 보안 인사이트, 분석 읽기 권한입니다.

Apply preset → Read only 또는 Apply preset → Full access를 사용하면 두 리소스를 한 번에 채울 수 있습니다. Full access는 두 리소스의 관리 스코프를 모두 부여합니다.

승인된 IP 주소로 키 제한(선택 사항)

IP allowlist 에서 Upload CSV 를 클릭하고 행마다 IP 주소나 주소 범위가 하나씩 들어 있는 파일을 선택하면 해당 주소에서 오는 요청만 허용합니다. 비워 두면 모든 주소에서 오는 요청을 허용합니다. 자세한 내용은 IP allowlist로 키 제한하기를 참고하세요.

키 생성 및 복사

Create API key를 클릭한 뒤 키 값을 복사합니다.

secret 값은 키를 만든 직후 한 번만 표시됩니다. 페이지를 떠나기 전에 복사해서 안전한 곳에 저장하세요. 값을 잃어버리면 새 키를 만들어야 합니다.

키 사용하기

모든 요청의 Lovable-API-Key 헤더에 키를 보냅니다. 다음 읽기 전용 예시를 실행하려면 Workspace: Read 또는 Read & write 권한이 필요합니다.

curl https://api.lovable.dev/v1/workspaces \
  -H "Lovable-API-Key: lov_YOUR_KEY" \
  -H "Lovable-Version: 2026-09-11" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

요청이 성공하고 키가 속한 워크스페이스가 반환되는지 확인하세요. IP allowlist를 설정했다면 허용된 아웃바운드 IP 주소에서 테스트하세요.

기존 키 관리하기

Workspace access tokens 섹션에는 워크스페이스의 모든 키가 표시됩니다. 각 키를 만든 사람, 생성 시각, 마지막 사용 시각, 크레딧 사용량도 함께 표시됩니다. 키의 View details 작업을 열면 스코프, 만료일, 크레딧 한도, IP allowlist를 볼 수 있습니다.

  • 크레딧 한도 변경: 키 메뉴를 열고 Edit credit limit을 클릭합니다. 언제든지 한도를 높이거나 낮추거나 제거할 수 있습니다.
  • IP allowlist 변경: 키 메뉴를 열고 Edit IP allowlist 를 클릭합니다. 기존 항목은 Current allowlist 라는 소스 하나로 표시됩니다. CSV를 업로드하면 항목이 추가됩니다. 목록을 교체하려면 Current allowlist 를 제거하고 새 CSV를 업로드하세요. 모든 소스를 제거하면 다시 모든 주소를 허용합니다.
  • 키 취소: 키 메뉴를 열고 Revoke key를 클릭한 뒤 확인합니다. 취소는 영구적이며 보통 즉시 적용되지만, 짧은 전파 지연이 있을 수 있습니다. 이미 수락된 작업은 취소하지 않습니다. 해당 키를 계속 사용하는 모든 대상은 접근 권한을 잃습니다.

이름, 스코프, 만료일은 키를 만들 때 고정됩니다. 변경하려면 대체 키를 만들고 통합을 업데이트한 다음, 정상적으로 동작하는지 확인한 뒤 이전 키를 취소하세요.

IP allowlist로 키 제한하기

IP allowlist는 승인된 IP 주소와 주소 범위에서 오는 요청으로만 키를 제한합니다. 덕분에 CI runner나 자체 백엔드처럼 예상한 서버에서만 키가 동작합니다. 키를 만들 때 설정하거나, 기존 키 메뉴의 Edit IP allowlist 에서 설정하세요.

행마다 항목 하나가 들어 있는 CSV 파일을 업로드합니다. 최대 3,000개 항목, 1MB까지 허용됩니다. 항목은 IPv4 또는 IPv6 주소이거나 203.0.113.0/24, 2001:db8::/48 같은 CIDR 표기 주소 범위입니다. Lovable은 IPv4의 /8, IPv6의 /32보다 넓은 범위를 거부합니다. Lovable API는 현재 IPv4로만 응답하므로 모든 목록에는 IPv4 항목이 최소 하나 있어야 합니다. Lovable은 유효하지 않은 항목이 담긴 행과 중복된 행을 건너뛰고, 건너뛴 개수를 보여줍니다. allowlist가 없는 키는 모든 주소에서 오는 요청을 받습니다.

목록에 없는 주소에서 온 요청은 403 ip_restricted로 실패합니다. Enterprise 플랜에서는 거부된 요청마다 워크스페이스 감사 로그에 User API key IP rejected 로 기록되며, allowlist 변경은 User API key updated 로 표시됩니다.

Lovable API 커넥터는 사용자의 주소가 아니라 Lovable의 커넥터 게이트웨이에서 API를 호출합니다. 제한된 키를 커넥터와 함께 쓰려면 allowlist에 커넥터 게이트웨이 IP 범위를 포함하세요.

키를 안전하게 보관하기

다음을 염두에 두세요.

  • 키는 코드나 버전 관리에 넣지 말고 secret manager 또는 환경 변수에 저장합니다.
  • 각 키에 필요한 스코프만 부여하고, "Never"보다 만료일 설정을 우선합니다.
  • 통합마다 별도의 키를 사용하면 다른 통합을 망가뜨리지 않고 특정 키만 취소할 수 있습니다.
  • Lovable은 GitHub secret scanning과 협력합니다. GitHub secret scanning이 노출된 지원 대상 Lovable API 키를 감지하고 보고하면(키는 lov_로 시작), Lovable이 해당 키를 자동으로 취소하고 이메일 알림을 보냅니다. 다른 곳에 노출된 키는 손상된 것으로 보고 직접 취소하세요.

키를 프로젝트 secret으로 저장할 때 이름을 LOVABLE_API_KEY로 지정하지 마세요. Lovable은 각 프로젝트에서 정확히 그 이름의 secret을 직접 만들고 관리하며, LOVABLE_로 시작하는 이름은 예약되어 있습니다. LOV_PUBLIC_API_KEY 같은 다른 이름을 선택하세요.

FAQ

관련 주제

On this page