For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/mobile/api.md (or send Accept: text/markdown).
모바일 API
앱이 서버와 통신하는 방법 — 세션, 도달 가능성, 페이로드.
초보자 연습
전제 조건: 아래 두 가지 초보자 가이드를 읽고 모바일 로컬 설정을 완료하세요. apps/mobile/.env.local에 Expo 값을 넣습니다. EXPO_PUBLIC_API_URL를 기기가 연결할 수 있는 백엔드 호스트로 설정하세요. 모바일 전용 결제에는 웹 백엔드가 없으므로 별도로 시작하거나 연결하세요. 성공적인 Expo 내보내기는 장치 또는 구매 승인이 아닌 JavaScript 번들을 증명합니다.
빠른 용어: 작업 영역은 한 팀의 별도 사용자, 데이터 및 설정입니다. 서버는 신뢰할 수 있는 백엔드입니다. 제공업체 키를 브라우저 및 전화 코드에 보관하세요. 마이그레이션은 테이블을 생성하거나 업데이트하는 버전이 지정된 데이터베이스 변경입니다. AI 모델은 응답하는 엔진입니다. 모델 카탈로그는 서버의 사용 가능한 모델 ID 및 가격 목록입니다. 공급자는 AI, 이메일, 청구 서비스와 같은 외부 서비스입니다. 자격은 작업 영역에서 기능을 사용할 수 있도록 하는 부여입니다. 웹훅은 한 서비스가 다른 서비스의 URL에 보내는 메시지입니다.
1. apps/mobile/.env.local에서 EXPO_PUBLIC_API_URL를 휴대폰에서 연결할 수 있는 실행 중인 백엔드 주소로 설정합니다. 물리적 장치에서 localhost를 사용하지 마십시오.
2. 모바일 로컬 설정에 따라 Expo를 시작하고 로그인한 후 작업 공간, 설정 및 채팅 화면을 엽니다.
3. 동일한 작업 공간에서 인증된 데이터를 기대합니다. 요청 시간이 초과되면 전화 및 컴퓨터 네트워크를 확인하고 모바일 전용 결제에서 별도로 백엔드를 시작하십시오.
사용자 정의 코드의 경우 제공된 prompts/README.md로 시작하고 가장 가까운 프롬프트(앱 화면의 경우 prompts/new-app-screen.md, 공개 페이지의 경우 prompts/new-landing-page.md)를 복사합니다. 서버, 데이터베이스 또는 공급자 작업의 경우 코딩 에이전트에게 이 가이드의 작업을 제공하고 AGENTS.md, .ai/PROJECT_CONTEXT.md 및 일치하는 .ai/ 미러를 읽도록 요청하세요. 여기에 이름이 지정된 정확한 소스 파일을 검사하십시오. 편집하기 전에 파일을 나열하고 확인합니다. 작업 공간 소유권과 서버 전용 비밀을 보존합니다. 차이점을 보여주세요. 원하는 동작, 입력 및 출력 필드, 허용된 역할, 예상되는 성공 및 오류, 테스트 계정, 공급자 또는 장치를 알려주십시오. 샘플 값을 사용하십시오. 절대 진짜 비밀을 붙여넣지 마세요.
기본 범위 이해
Expo에는 작업 공간, 설정, 채팅 및 RevenueCat 구매 화면과 함께 기본 인증/세션 및 딥 링크가 포함되어 있습니다. 공유된 비즈니스 동작 및 권한은 웹 백엔드/패키지에 유지됩니다. apps/mobile/src 아래의 기본 클라이언트는 공급자 자격 증명을 내장하지 않고 해당 API를 호출합니다.
세션 인증된 BFF를 사용하세요.
/api/mobile 경로에는 권한 부여, RevenueCat 구매 가용성 및 서버 동기화, 조직, 구성원, 초대, 감사, API 키, 웹후크, 도메인, 일정 및 기능 요청이 포함됩니다. 작업공간 소유권과 역할 확인을 유지합니다. 이는 sk_ 베어러 키 /api/v1 공개 계약과 다릅니다.
장치에 연결할 수 있는 EXPO_PUBLIC_API_URL 및 구성된 원본/구성표를 사용하세요. 공개 Expo 변수에는 공급자 자격 증명이 포함되지 않습니다.
네이티브 타겟에서 확인
지원하려는 장치/빌드에서 로드/오류/빈 상태, 다시 연결, 세션 만료, 금지된 관리 작업 및 딥 링크 반환을 확인하세요. Expo 내보내기는 기본 배송이나 구매 수락이 아닌 번들링을 증명합니다.
설치 및 설정
앱은 /api/mobile과 버전 관리된 /api/v1 표면의 API를 웹 앱의 쿠키 가정이 아닌 멤버 세션으로 호출합니다. EXPO_PUBLIC_API_URL은 클라이언트가 아는 유일한 오리진이며 설계상 공개이고 시크릿을 담지 않습니다.
세션 토큰은 Better Auth Expo 플로에서 오며 네이티브 보안 스토리지에 보관됩니다 — 평문 AsyncStorage나 번들된 설정에는 절대 저장하지 않습니다.
GET /api/mobile/entitlement # access state for the member
GET /api/mobile/organization # active workspace context
GET /api/mobile/usage # current-month AI spend, meter caps, and credit balance
GET /api/mobile/appearance # synced appearance bundle (GET/PUT)
POST /api/v1/ai-tasks # authorized work, same as web
Session: /api/auth/* (Better Auth Expo flow)
# Optional server-only token for authenticated Expo push sends:
# EXPO_ACCESS_TOKEN=구현 워크플로
첫 인증 요청 전에 저장된 세션을 해석하고, 서버가 만료를 보고하면 갱신하고, 폐기되면 깔끔하게 로그아웃합니다. API 도달 불가와 유효하지 않은 세션은 다른 상태로 취급하세요 — 하나는 재시도, 다른 하나는 로그인으로 돌아갑니다.
페이로드는 웹 계약과 동일하게 유지하세요. 어떤 클라이언트가 호출하든 서버는 동일한 워크스페이스·엔타이틀먼트·검증 규칙을 적용합니다.
검증 및 문제 해결
비행기 모드 실패, 세션 중간 토큰 만료, 폐기된 세션, 유효한 저장 토큰으로의 콜드 스타트를 테스트합니다. 닫혀서 실패하는(거부되는) 요청은 정상이고, 열려서 실패하는 것은 릴리스 전에 고쳐야 할 버그입니다.