인증 방식

Onttle REST API는 Bearer Token 방식으로 인증합니다. Project에서 발급한 API Key를 모든 요청의 Authorization 헤더에 포함해야 합니다.

API Key란?

API Key는 외부 애플리케이션이 특정 Project의 데이터에 접근할 수 있는 인증 수단입니다.

Project 범위: API Key는 특정 Project에 소속됩니다. 해당 Project의 데이터만 접근할 수 있습니다.
권한 선택: 읽기 전용 또는 읽기+쓰기 권한 중 선택합니다.
허용 호스트: 특정 도메인에서만 요청을 허용하도록 제한할 수 있습니다.

API Key 발급

대시보드에서 API Key를 발급할 Project를 엽니다.
좌측 메뉴에서 API Keys를 클릭합니다.
새 API Key 버튼을 클릭합니다.
이름을 입력합니다 (예: production-read).
권한을 선택합니다.
- 읽기: GET 요청만 허용합니다.
- 읽기+쓰기: GET, POST, PUT, PATCH, DELETE 요청을 모두 허용합니다.
허용 호스트를 입력합니다 (선택 사항).
생성을 클릭합니다.

[이미지 영역] API Key 생성 화면 (이름, 권한, 허용 호스트 입력 UI)

API Key는 생성 직후 한 번만 전체 값이 표시됩니다. 창을 닫기 전에 반드시 복사하세요.

인증 헤더 사용

모든 API 요청에 다음 헤더를 포함합니다.

Authorization: Bearer {API_KEY}

curl 예제

curl https://api.onttle.com/v1/{projectId}/tables/posts/contents \
  -H "Authorization: Bearer $ONTTLE_API_KEY"

TypeScript 예제

const res = await fetch(
  `https://api.onttle.com/v1/${projectId}/tables/posts/contents`,
  {
    headers: {
      Authorization: `Bearer ${process.env.ONTTLE_API_KEY}`,
      'Content-Type': 'application/json',
    },
  },
)

환경 변수로 관리하기

API Key는 코드에 직접 포함하지 말고 환경 변수로 관리합니다.

# .env.local (Next.js)
ONTTLE_API_KEY=your_api_key_here
ONTTLE_PROJECT_ID=your_project_id

서버 환경 변수는 클라이언트 번들에 포함되지 않습니다. 브라우저에서 직접 API를 호출할 때는 서버 경유 방식을 사용하세요.

읽기 vs. 읽기+쓰기 권한

작업	읽기	읽기+쓰기
GET 요청	O	O
POST / PUT / PATCH / DELETE	X	O
비공개 상태 콘텐츠 접근 (DRAFT 등)	X	O

퍼블릭 웹사이트처럼 콘텐츠를 조회만 하는 경우에는 읽기 전용 Key를 사용하세요. 쓰기 권한이 있는 Key는 서버 환경에서만 사용하세요.

보안 권장 사항

절대 하지 말아야 할 것

소스 코드에 API Key를 하드코딩하는 것
API Key를 Git에 커밋하는 것
쓰기 권한 Key를 브라우저 클라이언트 코드에 포함하는 것
API 응답 로그에 Key를 기록하는 것

권장 사항

환경 변수로 관리하고 .env.local을 .gitignore에 추가합니다.
서비스별로 별도의 API Key를 발급합니다 (운영/개발 분리).
쓰기 작업은 서버 측 API Route에서만 실행합니다.
노출이 의심되면 즉시 Key를 삭제하고 새 Key를 발급합니다.

API Key 교체 및 삭제

비활성화

일시적으로 Key를 차단하려면 API Keys 목록에서 해당 Key를 비활성화합니다. 비활성화된 Key로는 API 요청이 거부됩니다.

삭제

Key를 삭제하면 해당 Key로 이루어진 모든 요청이 즉시 거부됩니다. 삭제된 Key는 복구할 수 없습니다.

인증 오류 처리

오류	원인
`401 Unauthorized`	Authorization 헤더 누락, Key 값이 잘못됨, Key가 삭제됨
`403 Forbidden`	Key 권한 부족 (읽기 Key로 쓰기 시도), 허용 호스트 외 도메인

다음 단계

에러 코드 — 오류 상태 코드별 원인과 해결 방법을 확인합니다.
REST API 사용법 — 인증 헤더를 포함한 완전한 요청 예제를 확인합니다.