Connectors

앱을 Slack, Resend, ElevenLabs 같은 서드파티 서비스에 연결하세요. 자격 증명은 암호화되며 액션은 사전 인증됩니다.

Connectors를 사용하면 코드에서 API 키를 직접 관리하지 않고도 외부 서비스를 앱에 통합할 수 있습니다. 연결을 한 번 설정하고 프로젝트에 바인딩한 다음, 앱에서 사전 구축된 액션을 호출하면 됩니다. 자격 증명은 저장 시 암호화되며 프론트엔드 코드에 노출되지 않습니다.

사용 가능한 connectors

Connector	카테고리	인증 방식	기능
Resend	커뮤니케이션	API key	트랜잭션 이메일 전송, 일괄 이메일 전송, 인증된 도메인 목록 조회
Slack	커뮤니케이션	OAuth	메시지 게시, 채널 및 사용자 목록 조회, 메시지 반응 추가, 스레드 읽기
ElevenLabs	AI	API key	텍스트 음성 변환, 사용 가능한 음성 목록 조회, 효과음 생성

더 많은 connectors가 지속적으로 추가되고 있습니다.

Connectors 작동 방식

연결을 생성합니다 — 자격 증명을 제공합니다 (API 키 입력 또는 OAuth로 로그인)
연결을 프로젝트에 바인딩합니다 — 해당 프로젝트가 자격 증명을 사용할 수 있도록 승인합니다
앱에서 액션을 호출합니다 — 요청이 Proyecta Cloud를 거치며, Proyecta Cloud가 서버 측에서 자격 증명을 주입합니다

앱 코드는 원시 API 키나 OAuth 토큰에 직접 접근하지 않습니다. Connector 시스템이 인증, 속도 제한, 감사 로깅을 모두 처리합니다.

Connector 설정하기

Builder에서 프로젝트를 엽니다
Settings > Connectors로 이동합니다
카탈로그에서 connector를 클릭합니다 (예: Resend)
자격 증명을 입력합니다:
- API key connectors (Resend, ElevenLabs): 시크릿 키를 붙여넣습니다
- OAuth connectors (Slack): 로그인 후 접근을 승인합니다
연결에 이름을 지정합니다 (예: “Production Resend”)
연결이 자동으로 테스트되며, 유효한 경우 Active 상태로 표시됩니다

앱에서 Connector로 데이터 읽기

앱은 API 키가 번들에 포함되지 않은 채로 브라우저에서 직접 서드파티 API를 읽을 수 있습니다. 자격 증명은 플랫폼에 암호화된 상태로 남아 있고, 앱은 connector 이름, 액션, 타입이 지정된 입력값만 지정하면 플랫폼이 대신 호출해 줍니다.

import { useConnectorData, useHttpRead } from '@/hooks/useConnector.ts';

// A connector's own read action, as a cached query
const { data, isLoading, error } = useConnectorData('eleven-labs', 'listVoices');

// The generic HTTP-read connector, by endpoint name
const { data: feed } = useHttpRead('news-feed', { limit: 10 });

의도적으로 설계된 두 가지 가드레일을 알아두세요:

읽기 전용입니다. 플랫폼이 브라우저에서 안전하다고 표시한 액션만 호출할 수 있으며, 그 외에는 403이 반환됩니다. 쓰기 작업(Slack에 메시지 게시, 메일 발송, 카드 청구)은 브라우저에서 절대 호출할 수 없습니다.
URL이나 호스트를 전달할 수 없습니다. 범용 http-read connector의 입력값은 { endpointKey, params }이며, endpointKey 뒤의 URL은 앱 코드가 아니라 앱 소유자인 여러분이 설정합니다. 서드파티 키는 할당량이 측정되므로 응답은 서버 측에서 캐시되고 속도 제한이 적용됩니다.

404는 소유자가 아직 해당 connector를 연결하지 않았다는 뜻이며, UI에서 처리할 가치가 있는 경우가 바로 이것입니다.

AI에게 연결 작업 맡기기

Connector 코드를 직접 작성할 필요가 없습니다. AI Builder는 프로젝트에 바인딩된 connectors를 파악하고 통합 코드를 자동으로 생성할 수 있습니다:

"사용자가 가입하면 환영 이메일을 보내줘" — Resend connector 사용
"새 주문이 들어오면 Slack 메시지를 게시해줘" — Slack connector 사용
"아티클 페이지에서 오디오 내레이션을 재생해줘" — ElevenLabs connector 사용

Connector 액션 레퍼런스

Resend (`connectorId: 'resend'`)

액션	부작용	설명
`sendEmail`	write	단일 트랜잭션 이메일 전송
`sendBatch`	write	여러 이메일 일괄 전송
`listDomains`	read	인증된 발송 도메인 목록 조회

Slack (`connectorId: 'slack'`)

액션	부작용	설명
`postMessage`	write	채널에 메시지 게시
`listChannels`	read	워크스페이스의 채널 목록 조회
`listUsers`	read	워크스페이스 멤버 목록 조회
`reactToMessage`	write	이모지 반응 추가
`getThread`	read	스레드의 댓글 조회

ElevenLabs (`connectorId: 'eleven-labs'`)

액션	부작용	설명
`textToSpeech`	write	텍스트를 음성 오디오로 변환
`listVoices`	read	사용 가능한 음성 목록 조회
`generateSoundEffect`	write	AI 효과음 생성

연결 상태

상태	의미
Active	자격 증명이 유효하며 연결이 사용 준비 완료 상태입니다
Broken	자격 증명이 만료되거나 취소됨 — 복원하려면 자격 증명을 업데이트하세요

보안

자격 증명은 저장 시 AES-256-GCM으로 암호화됩니다
액션은 프로젝트별 connector당 분당 1,000 요청으로 속도가 제한됩니다
모든 액션 호출은 감사 추적과 함께 기록됩니다 (연결, 액션, 실행 시간, 상태)
연결은 전체 워크스페이스 범위로 적용됩니다

FAQ

동일한 연결을 여러 프로젝트에서 사용할 수 있나요?

네. 연결을 한 번 생성하면 동일한 워크스페이스 내 여러 프로젝트에 바인딩할 수 있습니다.

API 키가 만료되거나 취소되면 어떻게 되나요?

연결 상태가 Broken으로 변경됩니다. Settings > Connectors에서 자격 증명을 업데이트하면 복원됩니다.

프론트엔드에서 connector 액션을 호출할 수 있나요?

앱이 자격 증명을 직접 보유하는 일은 없습니다. 브라우저에서 안전한 읽기 액션은 Proyecta Cloud를 거쳐 프록시되며, Proyecta Cloud가 서버 측에서 자격 증명을 주입하므로 키가 번들에 포함되지 않습니다. 쓰기 액션은 브라우저에서 아예 호출할 수 없습니다.

커스텀 connector를 추가할 수 있나요?

아직은 불가능합니다. 커스텀 connector 정의는 로드맵에 포함되어 있습니다.

곧 출시 예정

추가 connectors (Google, Twilio, SendGrid 등)
커스텀 connector 정의 — 직접 API를 가져와 사용
연결된 서비스의 수신 이벤트를 위한 Webhook 수신
OAuth 게이트웨이 — 클라이언트에서 시작된 흐름에서도 토큰을 서버 측에 유지