Stack Auth项目REST API全面指南
项目概述
Stack Auth是一个现代化的身份验证解决方案，提供了一套完整的REST API接口，使开发者能够轻松集成用户认证和授权功能到各种应用程序中。无论您使用的是前端框架还是后端服务，Stack Auth都能提供统一、安全的认证机制。
API认证机制
Stack Auth API采用基于HTTP头的认证方式，所有请求都需要包含特定的认证头信息。以下是核心认证头字段：
curl https://api.stack-auth.com/api/v1/ \
-H "X-Stack-Access-Type: <either 'client' or 'server'>" \
-H "X-Stack-Project-Id: <your project UUID>" \
-H "X-Stack-Publishable-Client-Key: pck_<your publishable client key>" \
-H "X-Stack-Secret-Server-Key: ssk_<your secret server key>" \
-H "X-Stack-Access-Token: <the current user's access token>"
认证头详解
| 头字段 | 类型 | 描述 |
|---|---|---|
X-Stack-Access-Type |
"client" 或 "server" | 必需。指定API访问类型，"client"用于前端API，"server"用于后端API |
X-Stack-Project-Id |
UUID | 必需。项目唯一标识符，可在项目仪表板中找到 |
X-Stack-Publishable-Client-Key |
字符串 | 客户端访问必需。可公开的客户端密钥 |
X-Stack-Secret-Server-Key |
字符串 | 服务端访问必需。绝密的服务器密钥，不应暴露给客户端 |
X-Stack-Access-Token |
字符串 | 可选。当前用户的访问令牌，未提供时视为未登录状态 |
快速入门指南
1. 选择合适的API类型
根据您的应用场景选择正确的API访问类型：
- 客户端API：适用于前端应用，如浏览器或移动应用
- 服务端API：适用于后端服务器，具有完整的数据访问权限
2. 配置认证信息
根据选择的API类型配置相应的认证头：
- 客户端API需要
X-Stack-Publishable-Client-Key - 服务端API需要
X-Stack-Secret-Server-Key
3. 发起API请求
使用正确的端点URL和认证头信息发起HTTP请求。Stack Auth API遵循RESTful设计原则，支持常见的HTTP方法(GET, POST, PUT, DELETE等)。
4. 处理响应
API响应包含标准HTTP状态码和JSON格式的数据体。建议实现完善的错误处理逻辑，特别是针对常见的错误状态码。
常见问题解答
1. 支持哪些编程语言？
Stack Auth REST API可以与任何能够发送HTTP请求的编程语言配合使用，包括但不限于：
- JavaScript/TypeScript
- Python
- Java/Kotlin
- Go
- C#/.NET
- Ruby
- PHP
- Swift/Objective-C
- Dart
2. 客户端与服务端API的区别
客户端API特点：
- 仅能访问和修改当前认证用户的数据
- 使用可公开的客户端密钥
- 适合嵌入前端代码
服务端API特点：
- 具有完整的数据访问权限
- 使用绝密的服务器密钥
- 必须运行在受信任的后端环境
3. 错误处理最佳实践
Stack Auth API使用标准HTTP状态码表示请求状态，常见错误包括：
400 Bad Request：请求参数无效401 Unauthorized：认证失败或缺失403 Forbidden：权限不足404 Not Found：资源不存在429 Too Many Requests：请求过于频繁500 Internal Server Error：服务器内部错误
错误响应会包含JSON格式的详细信息，建议在客户端实现统一的错误处理机制。
4. 关于速率限制
Stack Auth实施了速率限制策略以确保系统稳定性。不同端点和访问类型有不同的限制。当超过限制时，API会返回429状态码，并在响应头中包含重试时间信息。
最佳实践建议
-
密钥管理：服务端密钥必须严格保密，不应出现在客户端代码或版本控制系统中
-
环境隔离：为开发、测试和生产环境使用不同的项目ID和密钥
-
错误日志：记录API错误响应，便于问题排查
-
请求验证：始终验证API响应数据，不假设请求一定会成功
-
版本控制：关注API版本更新，及时迁移到新版本
Stack Auth提供了灵活而强大的身份验证解决方案，通过合理使用其REST API，开发者可以快速构建安全可靠的用户认证系统。
