인증

모든 API 요청에는 Authorization 헤더에 Bearer 토큰이 필요합니다. Postlark는 두 가지 인증 방식을 지원합니다.

API Key (MCP, CLI, 자동화에 권장)

Authorization: Bearer pk_live_xxxxxxxxxxxx

대시보드 → 설정 → API Keys에서 키를 발급하세요. 각 키는 특정 블로그에 바인딩됩니다.

JWT 세션 (대시보드 전용)

대시보드는 Supabase JWT 토큰으로 세션 기반 인증을 합니다:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT 인증 시 Postlark가 첫 번째 블로그를 자동 선택합니다. 특정 블로그를 지정하려면 X-Blog-Id 헤더를 포함하세요:

X-Blog-Id: blog-uuid-here

Scope (권한 범위)

API 키는 스코프 기반 권한을 지원합니다. 각 스코프는 특정 작업 집합에 대한 접근을 제어합니다.

스코프	설명
`*`	전체 접근 (모든 스코프)
`posts:read`	포스트 조회 (목록, 상세)
`posts:write`	포스트 생성, 수정, 삭제, 발행, 예약
`blogs:read`	블로그 설정 조회
`blogs:write`	블로그 설정 수정, API 키 관리
`analytics:read`	분석 데이터 조회
`search:read`	포스트 검색
`account:read`	프로필 조회
`account:write`	계정 삭제, 토큰 관리
`packs:read`	포스트 팩 잔고 조회
`packs:write`	포스트 팩 구매
`domains:read`	커스텀 도메인 상태 조회
`domains:write`	커스텀 도메인 등록/해제
`media:read`	업로드된 이미지 조회
`media:write`	이미지 업로드

{resource}:*를 사용하면 해당 리소스의 모든 작업에 접근할 수 있습니다 (예: posts:* = posts:read + posts:write).

새 키 생성 시 기본 스코프는 ["*"] (전체 접근)입니다. 대시보드 또는 API에서 키 발급 시 스코프를 제한할 수 있습니다.

토큰 만료

블로그 API 키는 기본적으로 만료되지 않습니다. 대시보드 → 설정 → API Keys에서 또는 DELETE /blogs/:id/api-keys/:keyId API로 언제든 폐기할 수 있습니다.

스코프 액세스 토큰은 만료 기간을 선택할 수 있습니다 (30일, 90일, 1년, 또는 무기한). 대시보드 → Access Tokens에서 또는 POST /account/tokens API로 생성합니다. 만료되거나 폐기된 토큰은 401 Unauthorized를 반환합니다.

JWT 세션 토큰은 Supabase Auth 설정에 따라 만료됩니다 (기본: 1시간). 대시보드가 토큰 갱신을 자동으로 처리합니다.

Rate Limit

플랜	요청/시간
Free	60
Starter	300
Creator	1,000
Scale	10,000
Enterprise	10,000+

모든 응답에 Rate Limit 헤더가 포함됩니다:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1711324800

초과 시 429 응답과 retry_after 초가 반환됩니다.

자세한 내용은 Rate Limits 레퍼런스를 참조하세요.

에러 형식

모든 에러는 일관된 JSON 형식을 따릅니다:

{
  "error": "not_found",
  "message": "Post not found"
}

상태	설명	예시
400	잘못된 입력	`"title is required"`
401	누락되거나 무효한 토큰	`"Invalid API key"`
403	플랜 업그레이드 필요	`"Post limit exceeded. Free plan allows 10 total posts."`
404	리소스 없음	`"Post not found"`
409	중복 리소스	`"slug \"my-post\" is already taken"`
429	Rate Limit 초과	`"Rate limit exceeded. Limit: 60 requests/hour."`
500	서버 오류	`"Internal server error"`

기본 URL

https://api.postlark.ai/v1

인터랙티브 API 탐색기: api.postlark.ai/docs