> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建一个 API 令牌

> POST /console/token/

创建一个新的 Management API 密钥。此端点位于**常规**的 Scanova API 主机（`qcg-api.scanova.io`）上，其身份验证方式与任何其他已登录仪表盘请求相同——使用 OAuth 访问令牌，**而非** Management API 密钥。

<Note>
  这是您唯一需要从可信上下文中、以自己的登录身份发起的 Management API 相关调用，而不是从将要使用生成密钥的那个集成程序中发起。完整的双主机架构请参见[概览](/zh/api-reference/management-api/overview)。
</Note>

## 请求

```
POST https://qcg-api.scanova.io/console/token/
Authorization: Bearer <your_oauth_access_token>
Content-Type: application/json
```

### 请求体参数

<ParamField body="name" type="string" required>
  该密钥的人类可读标签，例如 `"Zapier — production"`。会显示在仪表盘的密钥列表中，方便您区分不同密钥。
</ParamField>

<ParamField body="environment" type="string" default="sandbox">
  `sandbox`、`live`、`zapier`、`mcp` 之一。在密钥的整个生命周期内保持不变——决定了该密钥发出的每一次数据主机请求会检查哪一种套餐配额，以及对于 `zapier`/`mcp` 密钥，调用方客户端必须发送哪种 `User-Agent` 请求头。完整的映射关系参见[套餐配额](/zh/api-reference/management-api/overview#plan-quota)。
</ParamField>

<ParamField body="expiry" type="integer" default="-1">
  `-1`（永不过期）、`30`、`90` 或 `365` 之一——创建后经过多少天该密钥停止生效。没有办法延长现有密钥的有效期；请创建一个新密钥。
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://qcg-api.scanova.io/console/token/" \
    -H "Authorization: Bearer <your_oauth_access_token>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Zapier — production",
      "environment": "zapier",
      "expiry": 365
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "name": "Zapier — production",
    "key": "401f7ac837da42b97f613d789819ff93537bee6a",
    "environment": "zapier",
    "expiry": 365,
    "created_by": {
      "id": 1042,
      "full_name": "Jordan Lee",
      "email": "jordan@example.com"
    },
    "created": "2026-08-16T09:12:33.512000Z",
    "expiry_date": "2027-08-16T09:12:33.512000Z",
    "expired": false,
    "usage_count": 0
  }
  ```
</ResponseExample>

### 响应字段

<ResponseField name="key" type="string">
  原始的 Management API 密钥。**这是唯一一次响应会返回完整的密钥值**——不存在事后重新显示/获取的端点，请立即妥善保存。
</ResponseField>

<ResponseField name="expiry_date" type="string | null">
  根据 `created` 加上 `expiry` 天数计算出的绝对到期时间戳，当 `expiry` 为 `-1`（永不过期）时为 `null`。
</ResponseField>

<ResponseField name="expired" type="boolean">
  该密钥是否已经过了其 `expiry_date`。已过期的密钥在数据主机上身份验证会失败，但不会被自动删除——如果您想将其从列表中移除，请通过 [`DELETE /console/token/{key}/`](/zh/api-reference/management-api/tokens/remove) 显式删除。
</ResponseField>

<ResponseField name="usage_count" type="integer">
  此特定密钥在其整个历史中被使用的请求次数总计。这与下方[用量端点](/zh/api-reference/management-api/tokens/usage-stats)返回的、汇总同一 environment 下所有密钥的聚合数字不同。
</ResponseField>

## 列出现有令牌

同样的 `console/token/` 路径也接受 `GET`（无需请求体）来列出账户上的每一个密钥，每个条目返回与创建响应相同的数据结构。您可以按 environment 筛选：`GET /console/token/?environment=live`。

<Note>
  创建和列出令牌都会使用请求中的 `environment` 重新检查套餐配额——创建时是请求体字段，列出时是查询参数，若省略则默认为 `sandbox`。如果您的套餐在 sandbox 和 live 之间的配额不同，在列出 live environment 的密钥时请显式传入 `?environment=live`，否则默认会检查 sandbox 配额。
</Note>

## 相关内容

* [Management API 概览](/zh/api-reference/management-api/overview) —— 本端点的 `environment` 字段所对应的双主机架构与按 `environment` 划分的配额映射。
* [移除一个 API 令牌](/zh/api-reference/management-api/tokens/remove) —— 吊销在此创建的密钥。
* [用量统计](/zh/api-reference/management-api/tokens/usage-stats) —— 同一 environment 下所有密钥的聚合请求次数。
* [列出 / 创建二维码](/zh/api-reference/management-api/qr/list) —— 大多数集成项目在使用此处创建的密钥后调用的第一个数据端点。


## OpenAPI

````yaml api-reference/openapi/management-api.json POST /console/token/
openapi: 3.1.0
info:
  title: Scanova Management API (v2)
  description: >-
    The complete Scanova Management API — every endpoint available at
    management.scanova.io (QR codes, folders, tags, leads, forms, analytics,
    plans, shared users & roles), plus the token-creation and usage-stats
    endpoints used to authenticate against it. Every path and request/response
    shape below was verified live against a real API key and the actual running
    backend (Phase 7, 2026-08-16) — not guessed from reading urls.py alone.
  version: 2.0.0
servers:
  - url: https://management.scanova.io
    description: Management API — QR/folder/tag/lead/form/analytics/plans endpoints
security:
  - apiKeyAuth: []
paths:
  /console/token/:
    post:
      summary: Create an API token
      operationId: createApiToken
      responses:
        '201':
          description: Token created
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Send your Management API key as the raw value of the Authorization
        header — no "Bearer " or "Token " prefix, and no other characters.
        Example: `Authorization: 401f7ac837da42b97f613d789819ff93537bee6a`. A
        header containing more than one space-separated part is rejected
        outright. Requests also require the request's Host header to be the
        management API host (e.g. management.scanova.io) — the same key sent to
        the regular API host will not authenticate.

````