ZeroCloud 에서는 OpenAI 키 · AWS 키 같은 자격증명을 리소스가 갖고 있어요. 내 서비스(앱 · 서버)는 리소스 ID + 리소스 토큰 두 값만 알면 돼요. 키를 바꿔도 앱을 다시 배포할 필요가 없고, 한 앱만 끊고 싶으면 그 앱의 토큰만 회수하면 돼요.
1. 필요한 것
| 값 | 어디서 |
|---|---|
| 리소스 ID | 콘솔 리소스 상세 주소의 마지막 부분, 또는 MCP get_resource |
| 리소스 토큰 | MCP issue_resource_token 으로 발급 (MCP 연결하기) |
- 리소스는 먼저 만들고 자격증명까지 넣어 둬야 해요 → ZeroCloud 시작하기
- 리소스 토큰 발급 화면은 아직 콘솔에 없어요. MCP 를 쓸 수 없다면 문의해 주세요
- 토큰 값은 발급할 때 한 번만 보여요. 다시 조회할 수 없으니 바로 비밀 저장소에 넣어 두세요
- 앱마다 따로 발급하세요. 같이 쓰면 하나를 끊을 때 전부 끊겨요
2. 문서 보기 — 개발자 센터
콘솔 왼쪽 아래 개발자 센터 에 다 모여 있어요.
- Swagger UI 열기 — 전체 엔드포인트 문서
- OpenAPI 스펙 다운로드 — 원하는 언어로 클라이언트를 생성할 때
- Node / TypeScript SDK · Java / Spring SDK 예제
- MCP 연결 설정
3. Node / TypeScript 에서 부르기
SDK 는 OpenAPI 스펙에서 생성되어 API 와 같이 바뀌어요. 리소스 종류별로 리소스 ID 와 토큰을 넣어 클라이언트를 만들어요.
import { createZeroCloudClient } from '@zerocloud/sdk';
const zc = createZeroCloudClient({
baseUrl: 'https://api.zerocloud.im',
email: {
baseUrl: '<개발자 센터의 알림 API 주소>',
resourceId: process.env.EMAIL_RESOURCE_ID!,
resourceToken: process.env.EMAIL_RESOURCE_TOKEN!,
},
});
ai · storage 도 같은 모양이에요. 각 서비스의 API 주소와 전체 예제는 개발자 센터에 그대로 복사할 수 있게 있어요.
- 메일 보내기 → 메일 보내기
- 파일 올리기 → 스토리지에 파일 올리기
- AI 호출 —
zc.ai.chat({ prompt })한 줄이에요. 프로바이더 · 모델 · 키는 리소스가 갖고 있어요
패키지 설치가 안 되는 환경이라면 개발자 센터에서 OpenAPI 스펙을 내려받아 원하는 생성기로 클라이언트를 만들어도 같아요.
응답 코드로 알 수 있는 것
| 코드 | 뜻 | 할 일 |
|---|---|---|
| 401 | 토큰이 없거나 틀렸거나 회수됐어요 | 토큰 값 · 리소스 ID 짝을 확인하고, 회수했다면 새로 발급 |
| 403 | 이 리소스에 허용되지 않은 동작이에요 (예: 허용 목록에 없는 발신 주소, 자격증명이 비어 있는 리소스) | 리소스 설정 · 자격증명 확인 |
| 400 | 요청 값이 틀렸어요 | 응답 메시지에 빠진 항목이 적혀 있어요 |
토큰 바꾸기 (회수)
새 토큰을 먼저 발급해 앱에 배포하고, 새 토큰으로 잘 도는 걸 본 다음에 옛 토큰을 회수해요. 회수하는 순간 그 토큰을 쓰던 앱은 바로 401 이 나요.
막히면 → 자주 막히는 곳