API 参考已发布

RAILWISE-OS API 认证指南

RAILWISE-OS API 的认证方式说明，包括 API Key、JWT Token、OAuth2 的获取与使用

复核 2026-07-09入门公开可引用RailWise 技术团队

API 参考

RAILWISE-OS API 认证指南

AI语义标签: #API认证 #JWT #OAuth2 #APIKey #安全认证 #开发者指南

1. 认证概述

RAILWISE-OS API 支持三种认证方式，适用于不同的使用场景：

认证方式	适用场景	有效期	安全等级
API Key	服务端集成、自动化脚本	长期有效（可撤销）	⭐⭐⭐
JWT Token	Web/移动端应用、用户会话	2小时（可刷新）	⭐⭐⭐⭐
OAuth2	第三方应用集成、SaaS生态	按授权范围	⭐⭐⭐⭐⭐

提示：所有 API 请求必须通过 HTTPS 传输，未加密的 HTTP 请求将被拒绝。

2. API Key 认证

2.1 获取 API Key

登录 RAILWISE-OS 管理后台
进入 系统设置 → API 管理 → API Key
点击“新建 API Key”，填写名称与权限范围
复制生成的 Key（仅显示一次）

API Key 格式: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2.2 使用 API Key

在请求头中携带 X-API-Key：

curl -X GET "https://api.os.railwise.cn/v3/projects" \
  -H "X-API-Key: rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

// TypeScript / Axios
import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.os.railwise.cn/v3',
  headers: {
    'X-API-Key': 'rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
});

const projects = await client.get('/projects');

# Python / requests
import requests

headers = {
    'X-API-Key': 'rwsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://api.os.railwise.cn/v3/projects',
    headers=headers
)
projects = response.json()

2.3 API Key 权限范围

API Key 支持按模块授权：

权限标识	说明
`project:read`	读取项目信息
`project:write`	创建/修改项目
`task:read`	读取任务信息
`task:write`	派发/修改任务
`data:read`	读取监测数据
`data:write`	写入监测数据
`report:read`	读取报告
`report:write`	生成报告
`system:read`	读取系统配置
`system:admin`	系统管理权限

3. JWT Token 认证

3.1 获取 JWT Token

通过用户名密码换取 Token：

curl -X POST "https://api.os.railwise.cn/v3/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin@railwise.cn",
    "password": "your_password",
    "grant_type": "password"
  }'

响应示例：

{
  "code": 200,
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
    "scope": "project:read project:write data:read"
  }
}

3.2 使用 JWT Token

在请求头中携带 Authorization: Bearer <token>：

curl -X GET "https://api.os.railwise.cn/v3/projects" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

// TypeScript / Axios 拦截器自动附加 Token
import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.os.railwise.cn/v3',
});

// 请求拦截器
client.interceptors.request.use((config) => {
  const token = localStorage.getItem('rw_access_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// 响应拦截器：Token 过期自动刷新
client.interceptors.response.use(
  (response) => response,
  async (error) => {
    const originalRequest = error.config;
    if (error.response?.status === 401 && !originalRequest._retry) {
      originalRequest._retry = true;
      const refreshToken = localStorage.getItem('rw_refresh_token');
      const { data } = await axios.post(
        'https://api.os.railwise.cn/v3/auth/refresh',
        { refresh_token: refreshToken }
      );
      localStorage.setItem('rw_access_token', data.data.access_token);
      originalRequest.headers.Authorization = `Bearer ${data.data.access_token}`;
      return client(originalRequest);
    }
    return Promise.reject(error);
  }
);

3.3 Token 刷新

curl -X POST "https://api.os.railwise.cn/v3/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJSUzI1NiIs..."
  }'

4. OAuth2 认证

4.1 适用场景

OAuth2 适用于第三方应用（如企业微信、钉钉、自建系统）与 RAILWISE-OS 的集成。

4.2 授权流程

RAILWISE-OS 支持 Authorization Code 授权模式：

┌─────────────┐                                    ┌─────────────┐
│   第三方应用   │                                    │  RAILWISE-OS  │
└──────┬──────┘                                    └──────┬──────┘
       │                                                  │
       │ 1. 引导用户访问授权页                              │
       │ ───────────────────────────────────────────────> │
       │    GET /oauth/authorize?client_id=xxx&redirect_uri=xxx │
       │                                                  │
       │ 2. 用户登录并授权                                  │
       │ <─────────────────────────────────────────────── │
       │    302 跳转至 redirect_uri?code=AUTH_CODE         │
       │                                                  │
       │ 3. 用 Code 换取 Token                             │
       │ ───────────────────────────────────────────────> │
       │    POST /oauth/token                             │
       │                                                  │
       │ 4. 返回 Access Token                             │
       │ <─────────────────────────────────────────────── │
       │    { access_token, refresh_token, expires_in }   │
       │                                                  │

4.3 实现示例

// 第三方应用 OAuth2 集成示例
class RailWiseOAuthClient {
  private clientId: string;
  private clientSecret: string;
  private redirectUri: string;
  private baseUrl = 'https://api.os.railwise.cn/v3';

  constructor(config: {
    clientId: string;
    clientSecret: string;
    redirectUri: string;
  }) {
    this.clientId = config.clientId;
    this.clientSecret = config.clientSecret;
    this.redirectUri = config.redirectUri;
  }

  // 生成授权 URL
  getAuthorizationUrl(state: string): string {
    const params = new URLSearchParams({
      client_id: this.clientId,
      redirect_uri: this.redirectUri,
      response_type: 'code',
      scope: 'project:read data:read',
      state,
    });
    return `${this.baseUrl}/oauth/authorize?${params.toString()}`;
  }

  // 用 Code 换取 Token
  async exchangeCodeForToken(code: string): Promise<TokenResponse> {
    const response = await fetch(`${this.baseUrl}/oauth/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        grant_type: 'authorization_code',
        client_id: this.clientId,
        client_secret: this.clientSecret,
        code,
        redirect_uri: this.redirectUri,
      }),
    });
    return response.json();
  }
}

interface TokenResponse {
  access_token: string;
  token_type: string;
  expires_in: number;
  refresh_token: string;
  scope: string;
}

5. 安全最佳实践

5.1 API Key 安全

建议	说明
最小权限原则	为每个 Key 分配最小必要权限
定期轮换	建议每 90 天更换一次 API Key
环境变量存储	不要将 Key 硬编码在代码中
IP 白名单	为生产环境 Key 配置允许的 IP 范围
使用监控	定期检查 API Key 的使用日志

5.2 JWT 安全

// 安全存储示例
// 推荐使用 httpOnly Cookie，避免 XSS 攻击

// 登录成功后设置 Cookie
function setAuthCookies(response: LoginResponse) {
  // Access Token: 短期有效，内存存储
  sessionStorage.setItem('rw_access_token', response.access_token);

  // Refresh Token: httpOnly Cookie，防止 JS 读取
  document.cookie = `rw_refresh_token=${response.refresh_token}; ` +
    `HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=604800`;
}

6. 常见错误

错误码	说明	解决方案
`401001`	API Key 无效	检查 Key 是否正确，是否已撤销
`401002`	JWT Token 过期	使用 Refresh Token 刷新或重新登录
`401003`	JWT Token 无效	检查 Token 格式，是否被篡改
`401004`	权限不足	检查 API Key 或 Token 的权限范围
`401005`	OAuth Client 未授权	检查 Client ID 和 Secret 是否正确
`429001`	认证请求过于频繁	降低请求频率，联系技术支持提升配额

7. 相关文档

文档版本: v3.2.0 | 最后更新: 2026-07-08 | API版本: v3