AGI01
AGI01

认证授权

接口概述

认证授权接口用于管理用户身份认证和访问授权，包括用户注册、登录、密码管理等功能。

基本信息

  • 接口路径：/v1/auth
  • 需要认证：部分接口需要
  • 请求方式：POST/GET
  • 数据格式：JSON

API 接口

用户注册

请求

POST /v1/auth/register
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "your-password",
    "username": "username",
    "full_name": "张三",
    "phone": "+86-13800138000"
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "user": {
            "id": "user_abc123",
            "email": "user@example.com",
            "username": "username",
            "full_name": "张三",
            "created_at": "2024-02-01T10:00:00Z"
        },
        "verification_email_sent": true
    }
}

邮箱验证

请求

POST /v1/auth/verify-email
Content-Type: application/json

{
    "token": "verification-token-xyz789"
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "email": "user@example.com",
        "verified": true,
        "verified_at": "2024-02-01T10:30:00Z"
    }
}

用户登录

请求

POST /v1/auth/login
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "your-password",
    "remember_me": true
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "token_type": "Bearer",
        "expires_in": 3600,
        "user": {
            "id": "user_abc123",
            "email": "user@example.com",
            "username": "username",
            "full_name": "张三"
        }
    }
}

刷新令牌

请求

POST /v1/auth/refresh-token
Authorization: Bearer your-refresh-token

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "token_type": "Bearer",
        "expires_in": 3600
    }
}

重置密码请求

请求

POST /v1/auth/forgot-password
Content-Type: application/json

{
    "email": "user@example.com"
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "message": "重置密码邮件已发送",
        "email": "user@example.com"
    }
}

重置密码

请求

POST /v1/auth/reset-password
Content-Type: application/json

{
    "token": "reset-token-xyz789",
    "password": "new-password",
    "password_confirmation": "new-password"
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "message": "密码重置成功",
        "email": "user@example.com"
    }
}

修改密码

请求

POST /v1/auth/change-password
Authorization: Bearer your-access-token
Content-Type: application/json

{
    "current_password": "old-password",
    "new_password": "new-password",
    "new_password_confirmation": "new-password"
}

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "message": "密码修改成功",
        "updated_at": "2024-02-01T11:00:00Z"
    }
}

获取当前用户信息

请求

GET /v1/auth/me
Authorization: Bearer your-access-token

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "user": {
            "id": "user_abc123",
            "email": "user@example.com",
            "username": "username",
            "full_name": "张三",
            "phone": "+86-13800138000",
            "created_at": "2024-02-01T10:00:00Z",
            "email_verified": true,
            "phone_verified": true,
            "last_login_at": "2024-02-01T11:00:00Z"
        }
    }
}

退出登录

请求

POST /v1/auth/logout
Authorization: Bearer your-access-token

响应

{
    "status_code": 200,
    "status_message": "SUCCESS",
    "data": {
        "message": "退出登录成功"
    }
}

错误码

错误码 说明 解决方案
400 请求参数错误 检查请求参数是否符合要求
401 未授权 检查认证信息是否有效
403 权限不足 检查用户权限
404 资源不存在 检查请求的资源是否存在
409 资源冲突 检查是否存在重复注册等问题
429 请求过于频繁 控制请求频率

安全说明

1. 密码要求

  • 最小长度：8 个字符
  • 必须包含：大小写字母、数字
  • 建议包含：特殊字符
  • 不能使用：常见密码、个人信息

2. 令牌说明

  • access_token: 访问令牌，有效期 1 小时
  • refresh_token: 刷新令牌，有效期 30 天
  • 令牌格式：JWT
  • 传输方式：Bearer Token

3. 安全建议

  • 使用 HTTPS 传输
  • 定期轮换密码
  • 启用双因素认证
  • 监控异常登录

使用示例

Node.js

// 用户注册
const registerResponse = await client.auth.register({
    email: 'user@example.com',
    password: 'your-password',
    username: 'username'
});

// 用户登录
const loginResponse = await client.auth.login({
    email: 'user@example.com',
    password: 'your-password'
});

// 使用访问令牌
const client = new ZGIClient({
    auth: {
        token: loginResponse.data.access_token
    }
});

// 刷新令牌
const refreshResponse = await client.auth.refreshToken(
    loginResponse.data.refresh_token
);

Python

# 用户注册
register_response = client.auth.register(
    email='user@example.com',
    password='your-password',
    username='username'
)

# 用户登录
login_response = client.auth.login(
    email='user@example.com',
    password='your-password'
)

# 使用访问令牌
client = ZGIClient(
    auth={
        'token': login_response.data.access_token
    }
)

# 刷新令牌
refresh_response = client.auth.refresh_token(
    login_response.data.refresh_token
)

最佳实践

1. 令牌管理

  • 安全存储令牌
  • 及时刷新令牌
  • 正确处理过期
  • 退出时清除令牌

2. 错误处理

  • 处理认证失败
  • 实现优雅降级
  • 提供友好提示
  • 记录错误日志

3. 用户体验

  • 记住登录状态
  • 自动刷新令牌
  • 支持单点登录
  • 提供登录历史