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

# 身份验证概述

Localpayment 使用 OAuth 2.0 Bearer 令牌认证来保护 API 访问。所有 API 请求都需要在 `Authorization` 请求头中包含有效的访问令牌。本指南概述了认证概念和安全要求。

安全认证是 API 集成的基础。Localpayment 基于令牌的认证机制确保只有授权请求才能访问您的账户数据并处理交易。

> [card] OAuth 2.0
>
> 行业标准 Bearer 令牌认证

> [card] 短期令牌
>
> 60 分钟访问令牌，增强安全性

***

## 安全要求

> [!WARNING]
>
> **关键安全要求**
>
> 遵循以下做法，确保API集成安全。

> [card] HTTPS加密
>
> 所有 API 通信都必须使用 HTTPS 来保护传输中的数据。

> [card] 仅限服务器端
>
> API 请求必须仅来自安全服务器环境。

> [card] IP白名单
>
> 在控制面板中配置 IP 白名单以授权 API 调用

> [card] 安全凭证存储
>
> 使用环境变量或密钥管理系统

***

## 身份验证 endpoint

使用这些专用 endpoint 管理您的 API 身份验证：

> [card] [获取访问令牌](https://docs.localpayment.com/zh/reference/get-token.md)
>
> 使用您的 API 凭据获取新的访问令牌和刷新令牌

> [card] [刷新访问令牌](https://docs.localpayment.com/zh/reference/refresh-token.md)
>
> 使用刷新令牌获取新的访问令牌，无需重新验证身份

### 快速示例

**生成令牌：**

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/token/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "username": "user@example.com",
  "password": "<PASSWORD>"
}
'
```

**使用令牌：**

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/validation/document \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "country": "ARG",
  "document": {
    "id": "1791234561009",
    "type": "RUC"
  }
}
'
```

***

## 令牌过期

Localpayment 使用短期令牌以增强安全性：

> [card] 访问令牌
>
> **60 分钟**\\
>
> 用于 API 请求\\
>
> 生命周期短，更安全

> [card] 刷新令牌
>
> **120 分钟**\\
>
> 用于获取新的访问令牌\\
>
> 生命周期长，更方便

### 令牌生命周期

1. **获取令牌**：通过[获取访问令牌](https://docs.localpayment.com/zh/reference/get-token.md)申请一对访问令牌和刷新令牌。
2. **重复使用访问令牌**：在访问令牌有效期内，每个请求都发送同一个访问令牌。
3. **过期后续期**：当访问令牌过期或收到 401 未授权响应时，通过获取访问令牌申请新的令牌对。
4. **替换已存储的令牌对**：存储两个新令牌，并丢弃之前的令牌。

> [!TIP]
>
> **使用刷新 endpoint**
>
> 如果您的集成已在使用[刷新访问令牌](https://docs.localpayment.com/zh/reference/refresh-token.md) endpoint，它仍然可用。每次刷新成功都会返回新的令牌对，您发送的刷新令牌随即失效。
>
> 新的获取访问令牌请求也会使同一用户和集成此前签发的刷新令牌失效。

***

## 令牌管理最佳实践

> [card] 每个集成一对令牌
>
> 每个用户和集成只保留一对令牌，并在所有进程和 worker 之间共享。

> [card] 替换整个令牌对
>
> 每次申请或刷新令牌后，同时存储新的访问令牌和新的刷新令牌。

> [card] 避免并行登录
>
> 不要使用同一用户并行申请令牌。每次新的令牌申请都会使之前的刷新令牌失效。

> [card] 不要重试失败的刷新
>
> 如果刷新返回 401，请通过获取访问令牌申请新令牌，而不要重试同一个刷新令牌。

***

## 错误处理

> [card] 401 未授权
>
> **令牌无效或已过期** \\
>
> 解决方案：通过[获取访问令牌](https://docs.localpayment.com/zh/reference/get-token.md)申请新令牌。如果刷新返回此错误，请不要重试同一个刷新令牌。

> [card] 401 未授权
>
> **IP 未加入白名单**\\
>
> 获取访问令牌会返回 "Invalid IP for user. Please validate that 203.0.113.10 is whitelisted in your account settings."\\
>
> 解决方案：在控制面板中将您的服务器 IP 添加到[白名单](https://docs.localpayment.com/zh/docs/dashboard-whitelist-your-ips.md)。


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