문서 · 레퍼런스

프로젝트 API

프로젝트마다 주소가 있고, supabase-js를 그대로 붙여 써요. 아래 경로는 서버 코드와 테스트로 맞춰 둔 목록이에요.

주소와 키

프로젝트 주소는 https://<ref>.<zone>이에요. 요청마다 apikey 헤더(또는 Authorization: Bearer)로 키를 보내요. 공개 키(publishable)는 브라우저용이고 접근 규칙(RLS)을 따라요. 비밀 키(secret)는 모든 규칙을 건너뛰니 서버에서만 써요. 로그인한 사용자의 토큰을 Authorization: Bearer로 보내면 그 사용자로 실행돼요. 키는 API 키 화면에 있어요.

curl "https://abcdefghijklmnopqrst.end.blackall.ai/rest/v1/notes?select=id,title" \
  -H "apikey: <publishable key>"

supabase-js 호환

경로·쿼리·헤더·응답 모양이 Supabase와 같아서 @supabase/supabase-js를 그대로 써요. 주소와 키만 바꾸면 돼요. 각 표의 supabase-js 열은 그 경로를 부르는 함수예요.

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://abcdefghijklmnopqrst.end.blackall.ai', '<publishable key>')

데이터 (/rest/v1)

PostgREST와 같은 쿼리 언어예요. 표 이름이 경로이고, 열 이름이 쿼리 매개변수예요. 모든 요청은 호출한 사람의 역할과 접근 규칙(RLS)으로 실행돼요.

쿼리 매개변수

필터 연산자

아래 연산자만 받고, 모르는 연산자는 거절해요. 앞에 not.을 붙이면 반대 조건이에요.

헤더

함수 호출 (rpc)

/rest/v1/rpc/<함수>는 프로젝트 스키마의 SQL 함수를 호출한 사람의 역할로 실행해요. POST는 본문이 인자예요. GET은 인자와 이름이 같은 쿼리 매개변수가 인자이고, 나머지는 결과 필터예요.

const { data, error } = await supabase
  .from('notes')
  .select('id, title, author(name)')
  .eq('done', false)
  .order('created_at', { ascending: false })
  .range(0, 19)

await supabase.from('notes').insert({ title: 'Hello' }).select().single()
await supabase.rpc('search_notes', { query: 'hello' })

curl "https://abcdefghijklmnopqrst.end.blackall.ai/rest/v1/notes?select=id,title&done=eq.false&order=created_at.desc&limit=20" \
  -H "apikey: <publishable key>" \
  -H "Prefer: count=exact"

지원하지 않는 것

• 집계(count(), sum() 등)와 스프레드(...rel(*)) select
• public이 아닌 스키마
• 한 번에 1000행을 넘는 읽기 (limit은 1000에서 잘려요)

인증 (/auth/v1)

GoTrue와 같은 경로와 응답이에요. 이메일·비밀번호, 매직 링크, 익명 로그인, 소셜 로그인(PKCE 포함), TOTP 2단계 인증, 비밀 키로 하는 사용자 관리를 지원해요.

토큰 받기 (grant_type): password, refresh_token, pkce, id_token(Google·Apple의 ID 토큰).

소셜 로그인 제공자: google, kakao, naver, apple, github, gitlab, microsoft, facebook, line, discord, x, bitbucket, figma, linkedin_oidc, notion, twitch, slack_oidc, spotify, zoom, azure, keycloak, workos, twitter, slack. 제공자 설정은 콘솔이나 관리 API의 set_auth_provider로 해요.

await supabase.auth.signUp({ email: '[email protected]', password: 'a-long-passphrase' })
await supabase.auth.signInWithPassword({ email: '[email protected]', password: 'a-long-passphrase' })
await supabase.auth.signInWithOAuth({ provider: 'google', options: { redirectTo: 'https://app.example.com' } })
const { data: { user } } = await supabase.auth.getUser()

지원하지 않는 것

• TOTP가 아닌 2단계 인증 (WebAuthn, 전화)
• 재인증(reauthenticate)과 신원 연결(linkIdentity). 연결 끊기만 돼요
• auth.admin.inviteUserByEmail. 대신 generateLink({ type: 'invite' })를 써요

파일 (/storage/v1)

Supabase Storage와 같은 경로예요. 파일 기록은 프로젝트의 표에 있어서, 파일을 누가 읽고 쓸지는 그 표의 접근 규칙이 정해요.

파일 하나는 기본 50MB까지 받아요(버킷마다 더 낮게 정할 수 있어요). 서명 URL은 최대 7일, 업로드용 서명 URL은 2시간 유효해요. 버킷 이름은 소문자·숫자·.·_·-이에요.

업로드는 본문 그대로(Content-Type이 파일 형식) 보내거나 multipart/form-data로 보내요. POST는 같은 이름이 있으면 거절하고(x-upsert: true면 덮어씀), PUT은 덮어써요.

이미지 변환

/render/image/{public|authenticated|sign}/<버킷>/<경로>에 쿼리로 줘요. 이미지 변환기가 없는 서버에서는 원본을 그대로 주고 x-blackwall-transform 헤더로 알려 줘요.

const bucket = supabase.storage.from('avatars')
await bucket.upload('me.png', file, { upsert: true })
const { data } = bucket.getPublicUrl('me.png', { transform: { width: 200, height: 200 } })
const { data: signed } = await bucket.createSignedUrl('me.png', 3600)

지원하지 않는 것

• 파일마다 다른 캐시 설정(cacheControl 옵션)은 저장하지 않아요

실시간 (/realtime/v1)

wss://<ref>.<zone>/realtime/v1/websocket?apikey=<키>&vsn=1.0.0은 Phoenix 채널(supabase-js가 쓰는 것)이에요. vsn=2.0.0은 배열 모양 메시지와 바이너리 브로드캐스트예요. /realtime/v1(websocket 없이)은 같은 기능의 단순한 JSON 프로토콜이에요.

채널 주제는 realtime:<이름>이에요. 같은 이름에 들어온 클라이언트끼리 브로드캐스트와 접속 상태(presence)를 나눠요.

클라이언트가 보내는 이벤트

서버가 보내는 이벤트

postgres_changes는 콘솔이나 set_realtime으로 실시간을 켠 표에서만 와요. 각 행은 받는 사람의 접근 규칙으로 확인한 뒤 보내요. 필터는 열=eq|neq|lt|lte|gt|gte|in.값이에요.

supabase
  .channel('room-1')
  .on('broadcast', { event: 'cursor' }, ({ payload }) => console.log(payload))
  .on('presence', { event: 'sync' }, () => console.log('online'))
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'notes', filter: 'done=eq.false' }, (change) => console.log(change.new))
  .subscribe()

wss://abcdefghijklmnopqrst.end.blackall.ai/realtime/v1/websocket?apikey=<publishable key>&vsn=1.0.0

{"topic":"realtime:room-1","event":"phx_join","payload":{"config":{"broadcast":{"self":false},"presence":{"key":"me"},"postgres_changes":[{"event":"*","schema":"public","table":"notes"}]}},"ref":"1","join_ref":"1"}
{"topic":"realtime:room-1","event":"broadcast","payload":{"type":"broadcast","event":"cursor","payload":{"x":1}},"ref":"2","join_ref":"1"}
{"topic":"phoenix","event":"heartbeat","payload":{},"ref":"3"}

지원하지 않는 것

• 비공개 채널(config.private: true)
• UPDATE의 이전 값 (old는 비어 있어요)

함수 (/functions/v1)

/functions/v1/<이름>은 배포한 함수를 불러요. 모든 HTTP 메서드를 그대로 전하고, 본문은 2MB까지예요. 비공개(기본) 함수는 이 프로젝트의 키가 있어야 부를 수 있어요: 공개 키(anon), 로그인한 사용자의 토큰(authenticated), 비밀 키(service_role). 공개 함수는 키 없이 불러요. 함수는 토큰 대신 확인된 클레임을 받아요. 이름은 소문자로 시작하는 소문자·숫자·-이에요.

const { data, error } = await supabase.functions.invoke('hello', { body: { name: 'world' } })

curl -X POST "https://abcdefghijklmnopqrst.end.blackall.ai/functions/v1/hello" \
  -H "Authorization: Bearer <user token or secret key>" \
  -H "content-type: application/json" \
  -d '{"name":"world"}'

그 밖의 경로

오류

오류는 경로마다 Supabase 클라이언트가 읽는 모양 그대로예요. 데이터는 PostgREST처럼 code(PGRST…), message, details, hint이고, 인증은 GoTrue처럼 code, error_code, msg(토큰 받기는 OAuth의 error, error_description도), 파일은 storage-js처럼 statusCode, error, message예요. 메시지는 Accept-Language(한국어, 영어, 일본어)를 따라요.

{ "code": "PGRST116", "message": "…", "hint": null, "details": "…" }