인증
Turso API는 요청 인증에 API 토큰을 사용해요. Turso CLI와 인증 API로 API 토큰을 만들고 취소할 수 있어요.
출처: 문서
본문
토큰은 세 가지 수준의 제한으로 발급할 수 있어요:
| 제한 수준 | 할 수 있는 일 | 발급 방법 |
|---|---|---|
| Organization-scoped | 단일 조직에 한정돼요. | turso auth api-tokens mint my-token --org my-org |
| Group-scoped | 조직 안의 하나의 그룹에 고정되고, 선택한 권한 집합을 가져요. | turso auth api-tokens mint my-token --org my-org --group default --read-only |
| Unrestricted (지원 중단) | 호출자가 속한 모든 조직에 대해 작동해요. | turso auth api-tokens mint my-token |
Unrestricted (cross-org) 토큰은 지원 중단 예정이며 향후 릴리스에서 제거될 거예요. 새 토큰은 항상 --org로 조직에 한정하세요. 기존 unrestricted 토큰은 당분간 계속 동작하지만, 가급적 빨리 scoped 토큰으로 교체하는 게 좋아요.
# Token scoped to a single organization
turso auth api-tokens mint my-token --org my-org
# Group-scoped token, read-only (tighter scope, for automations that only need one group)
turso auth api-tokens mint my-token --org my-org --group default --read-only
# Token with access to all organizations — deprecated
turso auth api-tokens mint my-token
--org로 토큰을 단일 조직에 한정하세요. 특히 CI/CD와 프로덕션 환경에서 중요해요.- API 토큰을 다룰 때는 환경 변수를 사용하세요.
- 저장소나 CI/CD Actions를 포함해 API 토큰을 공개 장소에 절대 공유하지 마세요.
Turso는 Bearer 인증을 사용하며, 보호된 모든 요청의 Authorization 헤더에 API 토큰을 담아 보내야 해요:
Authorization: Bearer ***
그룹 스코프 토큰
그룹 스코프 토큰은 조직 안의 하나의 그룹에 고정되고, 허용된 작업 목록이 명시된 Platform API 자격 증명이에요. 조직 나머지 부분에는 접근하지 못하면서 단일 그룹 안에서 데이터베이스를 프로비저닝하고 관리해야 하는 자동화에 딱 맞는 형태예요.
그룹 스코프 토큰을 발급하는 호출자는 조직의 admin이나 owner여야 해요.
그룹 스코프 토큰은 컨트롤 플레인 자격 증명이에요 — Turso Platform API에 대한 요청을 승인해요. 애플리케이션이 데이터베이스를 쿼리할 때 쓰는 SQL 엔진 토큰과는 독립적이에요. 두 시스템은 키 재료나 용어를 공유하지 않아요.
스코프 용어
플랫폼은 read-only와 full-access 프리셋을 서버 측에서 개별 스코프로 확장해요. 그래서 토큰 생성 후에 보이는 값은 항상 개별 스코프예요.
| 스코프 | 허용 범위 |
|---|---|
read |
모든 GET 방식 라우트: 데이터베이스/그룹 나열·조회, 설정, 사용량, 인스턴스, 위치. |
db:create |
그룹 안에 데이터베이스 생성 (POST /databases), 덤프로 시드, 복원. |
db:delete |
그룹 안의 데이터베이스 삭제. |
db:configure |
데이터베이스 설정 패치, 이전, 깨우기, 인스턴스 추가·제거. |
db:mint-token |
그룹 안 데이터베이스용 SQL 엔진 토큰 또는 TLS 클라이언트 인증서 발급. |
db:rotate-creds |
데이터베이스 서명 키를 교체해서 해당 DB에 발급된 모든 SQL 토큰을 무효화. |
group:configure |
그룹 설정, 이름 변경, 업데이트, unarchive, 위치 추가·제거. |
group:mint-token |
그룹 수준 SQL 엔진 토큰 발급. |
group:rotate-creds |
그룹 서명 키를 교체해서 그룹 내 어떤 데이터베이스에 발급된 SQL 토큰도 모두 무효화. |
db:mint-token과 db:rotate-creds는 의도적으로 분리된 스코프예요. 새 SQL 자격 증명 발급은 추가적(additive)이지만, 교체는 현재 사용 중인 모든 자격 증명을 무효화해서 실행 중인 애플리케이션을 중단시킬 수 있어요. 교체 권한은 꼭 필요한 자동화에만 부여하세요.
프리셋
| 프리셋 | 확장 결과 |
|---|---|
read-only |
read |
full-access |
위에 나열된 모든 개별 스코프. |
그룹 생성, 그룹 삭제, 그룹 이전, AWS 마이그레이션은 어떤 스코프로도 그룹 스코프 토큰에서 실행할 수 없도록 의도적으로 막혀 있어요 — 이 작업들은 조직 수준 자격 증명으로만 가능해요.
수명 주기
- 그룹 스코프 토큰은 이름이 아니라 그룹의 UUID로 고정돼요. 그룹이 삭제된 뒤 같은 이름으로 새 그룹을 만들어도 기존 토큰은 이월되지 않고, 그룹과 함께 revoke돼요.
- 그룹을 삭제하면 그 그룹에 스코프된 모든 토큰이 연쇄적으로 revoke돼요.
- 그룹을 다른 조직으로 이전하면 그 그룹에 스코프된 모든 토큰이 연쇄적으로 revoke돼요.
조직 토큰 관리
두 엔드포인트로 관리자가 한 조직에 스코프된 모든 토큰을 한곳에서 관리할 수 있어요 — 대시보드의 조직 수준 토큰 테이블도 이걸 기반으로 동작해요:
GET /v1/organizations/{organizationSlug}/api-tokens— 발급 사용자 정보와 함께 모든 org-scoped 및 group-scoped 토큰을 나열해요.DELETE /v1/organizations/{organizationSlug}/api-tokens/{tokenId}— ID로 토큰을 revoke해요.
멤버와 뷰어도 같은 엔드포인트를 호출할 수 있지만, 자신이 발급한 토큰만 보고 revoke할 수 있어요.
베이스 URL
Turso API는 다음 URL에 있어요:
https://api.turso.tech
더 알아보기 (Learn more)
- 토큰 생성 — API 토큰을 만드는 엔드포인트
- 조직 토큰 목록 — 조직에 스코프된 토큰 나열
- 조직 토큰 revoke — 조직 토큰 취소
- 감사 로그 목록 — 조직 감사 로그 조회