API 키

API 키를 사용하면 다른 앱 — Ainalyn 데스크톱 앱, 명령줄, 또는 사용자 본인의 통합 — 이 사용자의 Convilyn 계정 권한으로 동작할 수 있습니다. 키는 웹 앱의 설정 → API 또는 전체 기능의 API 콘솔에서 관리합니다.

API 키의 용도

키는 사용자를 대신해 이루어지는 호출을 인증하므로, 브라우저 밖에서도 Convilyn을 사용할 수 있습니다:

키는 사용자를 대신해 동작하므로 비밀번호처럼 다루세요. 키를 가진 사람은 누구나 사용자의 크레딧을 사용할 수 있습니다.

설정 → API를 엽니다(먼저 로그인하세요).
키 생성을 선택하고 나중에 알아볼 수 있는 이름을 지정합니다 — 예를 들어 "내 데스크톱".
키의 범위(scopes) 와 필요 시 만료일(expiry) 을 선택합니다(둘 다 아래에서 설명). 기본값은 전체 액세스·만료 없음으로, 개인용 키에 적합합니다.
전체 키를 복사합니다. 키는 ck_로 시작하며 한 번만 표시되므로 — 안전한 곳에 보관하세요. 다시 볼 수 없습니다.

범위는 키가 할 수 있는 작업을 제한합니다:

새 키는 기본적으로 전체 액세스(읽기＋쓰기)입니다. 보고나 읽기 전용 자동화에만 쓰는 키라면 읽기만 선택할 수 있습니다 — 크레딧을 사용할 수 없으므로 유출되더라도 요금이 발생하지 않습니다.

키에 선택적 만료일을 설정할 수 있습니다. 만료일이 지나면 키는 자동으로 인증을 중단합니다. 비워 두면 만료되지 않는 키가 됩니다.

키를 Bearer 토큰으로 Authorization 헤더에 담아 보냅니다:

curl https://convilyn.corenovus.com/api/v1/workflows/catalog \
  -H "Authorization: Bearer ck_your_key"

ck_your_key를 생성한 키로 바꾸세요. 전체 프로그래밍 인터페이스 — Python SDK, convilyn CLI, REST API — 는 개발자 문서를 참조하세요.

설정 → API에서 다음을 할 수 있습니다:

키 교체 — 새 시크릿을 발급하고, 그동안 기존 키는 짧은 유예 기간(24시간) 동안 계속 작동하므로 중단 없이 새 키로 전환할 수 있습니다. 유예 기간이 지나면 기존 키는 자동으로 중지됩니다.
단일 키 폐기 — 즉시 동작을 멈추며 되돌릴 수 없습니다.
모두 폐기 — 키가 유출된 것으로 의심될 때 사용하는 인시던트 대응 기능입니다.

각 키의 활동이 기록되므로 비용과 상태를 파악할 수 있습니다:

API 액세스는 Free를 포함한 모든 플랜에 포함됩니다. 플랜 간 차이는 크레딧과 한도뿐이며, 기능에는 차이가 없습니다. 키로 이루어진 클라우드 호출은 웹 앱과 동일한 크레딧 잔액에서 차감됩니다.

HTTPS 엔드포인트를 등록하면 작업이 끝날 때 Convilyn이 해당 엔드포인트로 POST를 보내므로, 폴링 없이도 결과에 반응할 수 있습니다.

이벤트 — job.completed 및 job.failed.
서명됨 — 모든 전송에는 X-Convilyn-Signature 헤더(페이로드에 대한 HMAC-SHA256)가 포함되어, 수신 측이 Convilyn에서 온 것인지 검증할 수 있습니다. 서명 시크릿은 hook을 만들 때 한 번만 표시됩니다.
안정성 — 전송에 실패하면 지수 백오프로 재시도하고, 반복 실패 시 데드레터 큐(dead-letter queue)로 이동합니다. 전송은 작업과 분리되어 있어, 수신 측이 느리거나 실패해도 작업 자체가 지연되지 않습니다.
테스트 가능 — 실제로 사용하기 전에 hook에 샘플 이벤트를 보내 엔드포인트를 확인할 수 있습니다.

webhook 생성 및 관리 — 시크릿 표시, hook 활성화/비활성화, 테스트 이벤트 전송 — 는 API 콘솔에서 합니다.

전체 관리 화면이 필요하면 독립형 API 콘솔을 사용하세요 — Convilyn 계정으로 로그인합니다. 위의 모든 기능을 한곳에 모으고, 더 자세한 화면을 제공합니다:

웹 앱의 설정 → API는 핵심 기능(키, 사용량, 데스크톱 앱)의 빠른 보기이며, 콘솔은 전체 경험입니다.