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

# 身份验证

> 创建 API 密钥并对请求进行身份验证。

> [!NOTE]
>
> GetQR API 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

GetQR API 使用您的账户 API 密钥对每个请求进行身份验证。每位用户有一个密钥，它在一个工作区中代表您执行操作。

## 开始之前

* 您是工作区所有者或编辑者。查看者无法创建或使用 API 密钥。
* 工作区所有者拥有有效订阅。

## 创建 API 密钥

**1. 打开账户设置**

打开账户设置，进入 **API**。

**2. 生成密钥**

点击 **Generate API key**。

**3. 复制密钥**

显示并复制密钥。密钥以 `sk_live_` 开头。

您可以随时再次显示和复制密钥。设置页面还会显示密钥的创建时间和最近一次使用时间。

## 对请求进行身份验证

在每个请求的 `Authorization` 请求头中，将密钥作为 Bearer 令牌发送：

```bash theme={null}
curl "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer sk_live_..."
```

| 问题 | 响应 |
| - | - |
| 没有 `Authorization` 请求头 | `401 unauthorized`："Missing Authorization header." |
| 请求头不以 `Bearer ` 开头 | `400 bad_request`："Misconfigured authorization header. Did you forget to add 'Bearer '?" |
| 密钥未知或已重新生成 | `401 unauthorized`："Unauthorized: Invalid API key." |
| 您的角色是查看者 | `403 forbidden`："API access is not available for this role." |
| 工作区所有者的订阅未生效 | `403 forbidden`："Access denied: This account does not have an active subscription." |
| 您的工作区未启用 API | `404 not_found`："This endpoint is not available." |

[健康检查](https://docs.getqr.com/zh/api/endpoints/health.md)是唯一无需密钥即可使用的端点。

## 访问权限与角色

* **角色。** 只有工作区所有者和编辑者可以创建和使用 API 密钥，查看者无法使用。
* **工作区。** 每个密钥只属于一个工作区，所有请求都在该工作区中执行，无需传入工作区 ID。
* **实时检查。** 每个请求都会根据您当前的角色和工作区所有者的订阅检查访问权限。您自己的订阅不计在内。如果您的角色变为查看者，或所有者的订阅已结束，请求会返回 `403`，直到访问权限恢复。您无需更换密钥。
* **移除。** 如果您被移出工作区，您的 API 密钥会被删除。重新加入后，请生成新的密钥。

## 重新生成密钥

如果密钥泄露，或者不该拥有密钥的人获得了访问权限，请重新生成密钥。

> [!WARNING]
>
> 当前密钥会立即失效。所有使用它的应用或集成都会中断，直到您将其更新为新密钥。

**1. 点击 Regenerate**

在账户设置中进入 **API**，然后点击 **Regenerate**。

**2. 确认**

点击 **Regenerate key**。

**3. 更新您的应用**

复制新密钥，并在所有使用旧密钥的地方替换它。

## 妥善保管密钥

请像对待密码一样对待密钥：任何拿到密钥的人都可以在您的工作区中创建、更改和删除二维码。

* 将密钥存储在环境变量或密钥管理工具中，不要写在源代码里。
* 只从您的服务器调用 API。切勿将密钥放在网站、移动应用或其他用户能够查看的地方。
* 只与需要它的开发人员共享密钥。
* 一旦怀疑密钥泄露，请立即重新生成。

## 常见问题

> [accordion] 以前可用的密钥返回 401
>
> 密钥已被重新生成，或者您已被移出工作区且密钥已被删除。请从账户设置中复制当前密钥，或生成一个新密钥。

> [accordion] 每个请求都返回 403
>
> 请确认您的角色是所有者或编辑者，并且工作区所有者的订阅处于有效状态。访问权限一恢复，密钥即可再次使用。

> [accordion] 返回 404 "This endpoint is not available."
>
> API 目前处于 Beta 阶段，您的工作区尚未启用。

> [accordion] 看不到 API 设置
>
> 只有工作区所有者和编辑者能看到 API 设置，并且仅限已启用 API 的工作区。

## 后续步骤

> [card] [API 简介](https://docs.getqr.com/zh/api/introduction.md)

> [card] [错误](https://docs.getqr.com/zh/api/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.