gateway

앱 코드에서 회사 데이터 커넥터를 쓰는 operation 모음이에요. 커넥터·리소스 조회, 세션 발급, 안전 쿼리(query)와 호출(invoke)까지 게이트웨이를 거치는 표면이 다 여기 있어요. 모든 호출은 grant(권한)와 preset(허용 action)의 통제를 받고, 범위 지정 grant·행/열 접근 정책 같은 안전장치가 그 위에 얹혀요. 커넥터를 처음 연결하고 승인받는 흐름은 커넥터로 회사 데이터 연결하기 가이드에서 볼 수 있어요.

14 operations — 외부 connector 등록·discover·query·invoke·config

범위 지정 grant · 접근 정책 · EXPLAIN

query·invoke 계열 op 를 부르기 전에 알아야 하는 안전장치 규칙이다 (spec 168·169·171·172).

• grant 의 4번째 축 — scope_resource_paths (spec 172): grant 는 subject×connector×preset 에 범위 축이 더해진 4축이다. schema/table 문자열 배열(최대 200개, 중복 제거)로 "어디까지" 를 지정하며, 빈 배열/생략 = 커넥터 전체(기존 동작). 생성 시 지정하거나 tenant_admin 이 PUT /api/v1/tenants/{tenantID}/grants/{grantID}/scope (authorizationPutApiV1TenantsByTenantIDGrantsByGrantIDScope) 로 통째 교체한다. 회수·만료된 grant 는 409.
• 범위 지정 grant 의 자유 쿼리 거부 (spec 172): 판정은 fail-closed — 대상을 확정할 수 없으면 거부다. 자유 SQL(/gateway/query), REST invoke, 파일 file-invoke, database 미지정 document-invoke 는 403 scope_requires_target. 대상이 명시된 호출(document-invoke 의 database+collection)은 목록 안이면 허용, 밖이면 403 scope_out_of_range. 범위가 빈 grant 는 모든 경로에서 종전과 동일하다.
• 행·열 접근 정책의 스코프 (spec 169·171): 정책(access-policy)은 resource_path(적용 대상 schema/table — 비면 커넥터 전체)와 connector_id(소속 커넥터 — 비면 커넥터 무관)를 가진다. 관리 표면은 /api/v1/tenants/{tenantID}/access-policies CRUD 이고, 활성 grant 가 참조 중인 정책 삭제는 409 policy_in_use (spec 168 — 지우면 그 grant 의 쿼리가 전부 fail-closed 거부되기 때문).
• EXPLAIN action (spec 168): kind=db preset 의 action vocabulary 는 SELECT/INSERT/UPDATE/DELETE 에 EXPLAIN 이 추가됐다. EXPLAIN 은 read-only 로 분류돼 READ ONLY 트랜잭션에서 실행되고, EXPLAIN ANALYZE 로 위장한 쓰기는 엔진이 거부한다. 기본 "Read Only" preset 은 backfill 로 EXPLAIN 을 갖는다 (SELECT 없는 preset 은 대상 아님).

GET /api/v1/tenants/{tenantID}/connectors

gatewayGetApiV1TenantsByTenantIDConnectors

• 호출 권한: tenant_admin 테넌트에 등록된 connector 목록을 조회한다.

Path 파라미터 — pathParams 로 전달

Query 파라미터 — query 로 전달 (문자열 값)

응답 — 200 · OK

배열 응답 → SDK 는 {"value": [...]} 로 감싸 반환. 원소 필드:

에러 status: 400 401 403 500 — 에러 처리

GET /api/v1/tenants/{tenantID}/connectors/{connectorID}

gatewayGetApiV1TenantsByTenantIDConnectorsByConnectorID

• 호출 권한: tenant_admin

Path 파라미터 — pathParams 로 전달

응답 — 200 · OK

에러 status: 400 401 403 404 500 — 에러 처리

POST /api/v1/tenants/{tenantID}/connectors/{connectorID}/discover

gatewayPostApiV1TenantsByTenantIDConnectorsByConnectorIDDiscover

관리자가 등록 직후 5분 cron 안 기다리고 즉시 스키마/테이블/컬럼을 발견시킨다. 응답으로 발견된 tables/columns 카운트 + schemas + 일부 preview 를 반환.

• 호출 권한: tenant_admin
• 부수 효과: 발견 성공 시 connectors.last_discovered_at 갱신, 새 path INSERT, 사라진 path SoftDelete
• REST connector 등 discoverer 없는 engine 은 zero-value 응답 (정상 200)

Path 파라미터 — pathParams 로 전달

응답 — 200 · OK

에러 status: 400 401 403 404 500 — 에러 처리

GET /api/v1/tenants/{tenantID}/connectors/{connectorID}/resources

gatewayGetApiV1TenantsByTenantIDConnectorsByConnectorIDResources

• 호출 권한: tenant_admin 관리자가 grant 와 무관하게 connector 의 모든 active resource 를 조회한다. 사용자 면 (/me/connectors/{cID}/resources) 와 동일한 응답 shape 이지만 grant 체크 없음 — 운영자 / 관리 콘솔의 카탈로그 조회용.
• limit (1~500, 기본 100) · offset · q (name 부분일치) · parent_id · roots_only

Path 파라미터 — pathParams 로 전달

Query 파라미터 — query 로 전달 (문자열 값)

응답 — 200 · OK

페이지 응답 { items: [...], total, next_cursor } — next_cursor 는 마지막 페이지에서 생략돼요. items 원소 필드:

에러 status: 400 401 403 500 — 에러 처리

POST /api/v1/tenants/{tenantID}/gateway/document-invoke

gatewayPostApiV1TenantsByTenantIDGatewayDocumentInvoke

MongoDB connector 의 op 를 실행한다.

• 호출 권한: tenant_member (session 의 grant 보유 필요)
• 입력: session_id · op (find/insertOne 등) · collection · 기타 op-별 필드
• 권한: op → SQL action 매핑 (find→SELECT, insertOne→INSERT 등) 후 preset.Allows 체크 (spec 039 §R2)
• 부수 효과: audit emit (TypeAPICall), connector pool 캐시
• 범위 지정 grant 는 대상(database/collection)이 허용 목록 안이면 허용, 밖이면 403 scope_out_of_range. database 미지정 등 대상 미상이면 403 scope_requires_target (spec 172)

Path 파라미터 — pathParams 로 전달

Request Body — body 로 전달, wire 키(snake_case) 그대로

응답 — 200 · 실행 결과

에러 status: 400 401 403 404 500 — 에러 처리

POST /api/v1/tenants/{tenantID}/gateway/file-invoke

gatewayPostApiV1TenantsByTenantIDGatewayFileInvoke

Google Drive connector 의 file action 을 실행한다.

• 호출 권한: tenant_member (session 의 grant 보유 필요)
• 입력: session_id · action (file:list|file:get|file:search) · 기타 action-별 필드
• 권한: action 그대로 preset.Allows 체크 — native vocab (SQL 매핑 X)
• 응답: Drive API raw shape (id, name, mimeType, size, modifiedTime, parents, webViewLink). 본문 stream X.
• 부수 효과: audit emit (TypeAPICall). refresh_token revoke 시 connector auth_status='auth_expired' 전이.
• 범위 지정 grant 는 이 호출을 거부한다 (파일은 테이블 대상이 아님) — 403 scope_requires_target (spec 172)

Path 파라미터 — pathParams 로 전달

Request Body — body 로 전달, wire 키(snake_case) 그대로

응답 — 200 · OK

에러 status: 400 401 403 404 500 503 — 에러 처리

POST /api/v1/tenants/{tenantID}/gateway/invoke

gatewayPostApiV1TenantsByTenantIDGatewayInvoke

5단계: authz → policy in → engine.Invoke → policy out → audit.

• 호출 권한: tenant_member
• 범위 지정 grant 는 이 호출을 거부한다 (REST 경로는 테이블 대상을 명시할 수 없음) — 403 scope_requires_target (spec 172)

Path 파라미터 — pathParams 로 전달

Request Body — body 로 전달, wire 키(snake_case) 그대로

응답 — 200 · OK

에러 status: 400 401 403 404 500 — 에러 처리

POST /api/v1/tenants/{tenantID}/gateway/query

gatewayPostApiV1TenantsByTenantIDGatewayQuery

5단계: authz → policy in → engine.Execute → policy out → audit.

• 호출 권한: tenant_member
• 입력: session_id · sql · params? · action?
• 부수 효과: audit query emit (allow/deny/error)
• action 은 preset 의 kind=db vocab (SELECT/INSERT/UPDATE/DELETE/EXPLAIN) 로 판정한다. EXPLAIN 은 read-only 분류 — READ ONLY 트랜잭션에서 실행 (spec 168)
• 범위 지정 grant(scope_resource_paths 비어있지 않음)는 자유 SQL 을 거부한다 — 403 scope_requires_target (spec 172)

Path 파라미터 — pathParams 로 전달

Request Body — body 로 전달, wire 키(snake_case) 그대로

응답 — 200 · OK

에러 status: 400 401 403 404 500 — 에러 처리

POST /api/v1/tenants/{tenantID}/gateway/sessions

gatewayPostApiV1TenantsByTenantIDGatewaySessions

사용자가 connector 에 대한 active grant 의 preset 을 snapshot 으로 8시간 TTL session 시작.

• 호출 권한: tenant_member
• 입력: connector_id · mfa_verified?
• 부수 효과: gateway_sessions INSERT

Path 파라미터 — pathParams 로 전달

Request Body — body 로 전달, wire 키(snake_case) 그대로

응답 — 201 · Created

에러 status: 400 401 403 404 500 — 에러 처리

DELETE /api/v1/tenants/{tenantID}/gateway/sessions/{sessionID}

gatewayDeleteApiV1TenantsByTenantIDGatewaySessionsBySessionID

• 호출 권한: tenant_member (자기 세션만)

Path 파라미터 — pathParams 로 전달

응답 — 204 · No Content

본문 없음 → SDK 는 빈 map {} 반환

에러 status: 400 401 403 404 500 — 에러 처리

GET /api/v1/tenants/{tenantID}/me/connectors

gatewayGetApiV1TenantsByTenantIDMeConnectors

현재 사용자가 active grant 를 가진 connector 들을 반환. 없는 connector 는 노출 0 (FR-018).

• 호출 권한: tenant_member

Path 파라미터 — pathParams 로 전달

응답 — 200 · OK

배열 응답 → SDK 는 {"value": [...]} 로 감싸 반환. 원소 필드:

에러 status: 401 403 500 — 에러 처리

GET /api/v1/tenants/{tenantID}/me/connectors/{connectorID}/resources

gatewayGetApiV1TenantsByTenantIDMeConnectorsByConnectorIDResources

active grant 없는 connector 는 404 — 메타데이터 자체 노출 0 (FR-018).

• 호출 권한: tenant_member

Path 파라미터 — pathParams 로 전달

Query 파라미터 — query 로 전달 (문자열 값)

응답 — 200 · OK

페이지 응답 { items: [...], total, next_cursor } — next_cursor 는 마지막 페이지에서 생략돼요. items 원소 필드:

에러 status: 401 403 404 500 — 에러 처리

GET /config/public

configGetConfigPublic

로그인 / 로그아웃 / 만료 토큰 상태와 무관하게 호출 가능한 익명 endpoint. FE 가 부트스트랩 시 1회 호출 후 메모리 캐시. 현재 base_domain 만 반환.

응답 — 200 · OK

에러 status: 429 — 에러 처리

GET /api/v1/oauth/google/callback

gatewayGetOauthGoogleCallback · 302 → {status, location}

Google 동의 후 redirect 받는 endpoint. code + code_verifier 로 token 교환, Shared Drive 목록을 oauth_state row 에 저장. Accept 헤더 분기:

• text/html (브라우저): 302 redirect to return_to?state=... (FE 가 이어받음)
• application/json: 기존 JSON 응답 (자동화 / curl 용)
• 호출 권한: 인증된 사용자 (state 가 secret 역할 — 10분 TTL).
• 입력: code · state (query string)
• 부수 효과: oauth_states row 갱신 (callback_payload 채움)

Query 파라미터 — query 로 전달 (문자열 값)

응답 — 200 · Shared Drive 목록 (Accept: application/json)

302 응답 시 {"status": 302, "location": "..."} 반환 (redirect 미추종)

에러 status: 400 401 500 — 에러 처리