본문 바로가기
WIKI 기술 지식 베이스

API 토큰 생성

원문 보기 위키 갱신

API 토큰 생성 (Create API Token)

사용자 계정에 속한 새 API 토큰을 발급하는 엔드포인트예요. 토큰은 세 가지 수준으로 범위를 좁혀 발급할 수 있는데, 새 토큰에는 항상 조직 범위를 지정하는 게 좋아요.

출처: 문서

본문

Returns a new API token belonging to a user.

토큰은 좁혀지는 순서대로 세 가지 수준의 제한으로 발급할 수 있어요:

  • 조직 범위(Organization-scoped) — organization을 전달해요. 토큰은 그 조직 안의 리소스에만 동작할 수 있어요.
  • 그룹 범위(Group-scoped) — organization, group, scopes를 전달해요. 토큰은 조직 안의 한 그룹에 고정되고, scopes에 나열된 작업만 허용돼요. 호출자는 조직의 관리자 또는 소유자여야 해요.
  • 무제한(Unrestricted) (사용 중단됨) — 요청 본문 없이 호출해요. 토큰은 호출자가 속한 모든 조직에서 동작할 수 있어요. 무제한 토큰은 사용이 중단되었으며 향후 릴리스에서 제거될 예정이에요. 새 토큰에는 항상 organization을 전달하고, 기존 무제한 토큰은 범위가 지정된 토큰으로 교체하세요.

그룹 범위 토큰은 조직의 나머지 부분에는 손대지 못하면서 한 그룹 안에서 데이터베이스를 프로비저닝하고 관리할 수 있게 설계된 자동화용이에요.

응답의 `token`은 다시는 공개되지 않아요. 안전한 곳에 저장하고, 절대 공유하거나 소스 컨트롤에 커밋하지 마세요. **무제한(조직 간) 토큰은 사용이 중단되었으며 향후 릴리스에서 제거될 예정이에요.** 요청 본문에는 최소한 `organization`이라도 포함하세요. ```bash cURL (org-scoped) theme={null} curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \ -H 'Authorization: Bearer ***' \ -H 'Content-Type: application/json' \ -d '{"organization": "my-org"}' ``` 
curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \
  -H 'Authorization: Bearer ***'

curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \
  -H 'Authorization: Bearer ***' \
  -H 'Content-Type: application/json' \
  -d '{
    "organization": "my-org",
    "group": "default",
    "scopes": ["read-only"]
  }'

curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \
  -H 'Authorization: Bearer ***' \
  -H 'Content-Type: application/json' \
  -d '{
    "organization": "my-org",
    "group": "default",
    "scopes": ["db:create", "db:configure", "db:mint-token"]
  }'

import { createClient } from "@tursodatabase/api";

const turso = createClient({
  org: "...",
  token: "",
});

const apiToken = await turso.apiTokens.create("my-token");

OpenAPI

openapi: 3.0.1
info:
  title: Turso Platform API
  description: API description here
  license:
    name: MIT
  version: 0.1.0
servers:
  - url: https://api.turso.tech
    description: Turso's Platform API
security: []
paths:
  /v1/auth/api-tokens/{tokenName}:
    post:
      summary: Create API Token
      description: >-
        Returns a new API token belonging to a user.


        The token can be minted at three levels of restriction, in increasing
        order of narrowness:


        - **Organization-scoped** — pass `organization`. The token can only act
        on resources inside that organization.

        - **Group-scoped** — pass `organization`, `group`, and `scopes`. The
        token is pinned to a single group inside the organization and only the
        operations listed in `scopes` are allowed. The caller must be an admin
        or owner of the organization.

        - **Unrestricted** *(deprecated)* — no request body. The token can act
        on every organization the caller belongs to. **Unrestricted tokens are
        deprecated and will be removed in a future release.** Always pass
        `organization` for new tokens and rotate existing unrestricted tokens to
        scoped tokens.


        Group-scoped tokens are designed for automations that should be able to
        provision and manage databases inside a single group without being able
        to touch the rest of the organization.
      operationId: createAPIToken
      parameters:
        - $ref: '#/components/parameters/tokenName'
      requestBody:
        description: >-
          Optional restriction for the token. Omit the body for an unrestricted
          token, pass `organization` alone for an org-scoped token, or pass
          `organization` + `group` + `scopes` for a group-scoped token.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                organization:
                  type: string
                  description: >-
                    The organization slug to restrict this token to. Required
                    when `group` is set.
                  example: my-org
                group:
                  type: string
                  description: >-
                    The group name (inside `organization`) to restrict this
                    token to. Requires `organization` and a non-empty `scopes`
                    list.
                  example: default
                scopes:
                  type: array
                  items:
                    type: string
                    enum:
                      - read
                      - db:create
                      - db:delete
                      - db:configure
                      - db:mint-token
                      - db:rotate-creds
                      - group:configure
                      - group:mint-token
                      - group:rotate-creds
                      - read-only
                      - full-access
                  description: >-
                    Permissions to grant a group-scoped token. Each entry is
                    either an individual scope or one of the presets `read-only`
                    (expands to `read`) and `full-access` (expands to every
                    scope). Required and must be non-empty when `group` is set.
                    `db:mint-token` lets the token issue new SQL credentials;
                    `db:rotate-creds` invalidates every existing SQL token for
                    the database — they are deliberately separate because
                    rotation is destructive.
                  example:
                    - db:create
                    - db:configure
                    - db:mint-token
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  name: 1003799d-19af-4e04-9f91-bd42a76d9d41
                  id: 8624135b-a36a-42d5-8159-9c5d48f8e393
                  token:
                    type: string
                    description: >-
                      The actual token contents as a JWT. This is used with the
                      `Bearer` header, see [Authentication](/authentication) for
                      more details. **This token is never revealed again.**
                    example: ...
components:
  parameters:
    tokenName:
      name: tokenName
      in: path
      required: true
      schema:
        type: string
      description: The name of the api token.

더 알아보기 (Learn more)