API Authentication Guide

API Authentication Guide

1. Overview

RAILWISE API uses token-based authentication. All API requests must include a valid authentication token. This guide introduces the authentication methods, token management, and security best practices.

2. Authentication Methods

2.1 API Key Authentication

API Key is the simplest authentication method, suitable for server-to-server calls.

Obtain API Key

1. Log in to RAILWISE Console
2. Go to Settings > API Keys
3. Click Create API Key
4. Copy and save the API Key

Use API Key

Include the API Key in the request header:

curl -H "X-API-Key: YOUR_API_KEY"   https://api.railwise.cn/v1/projects

2.2 OAuth 2.0 Authentication

OAuth 2.0 is suitable for third-party application integration, supporting authorization code mode and client credentials mode.

Authorization Code Mode

Suitable for applications with user interaction:

1. User visits application
2. Application redirects user to RailWise authorization page
3. User authorizes application
4. RailWise redirects back to application with authorization code
5. Application exchanges authorization code for access token
6. Application uses access token to call API

Client Credentials Mode

Suitable for server-to-server calls without user interaction:

# Request token
curl -X POST https://api.railwise.cn/oauth/token   -H "Content-Type: application/x-www-form-urlencoded"   -d "grant_type=client_credentials"   -d "client_id=YOUR_CLIENT_ID"   -d "client_secret=YOUR_CLIENT_SECRET"

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use Access Token

curl -H "Authorization: Bearer ACCESS_TOKEN"   https://api.railwise.cn/v1/projects

2.3 JWT Authentication

JWT (JSON Web Token) is the built-in authentication method of RAILWISE-OS, suitable for frontend-backend separation applications.

Obtain JWT Token

curl -X POST https://api.railwise.cn/v1/auth/login   -H "Content-Type: application/json"   -d '{
    "username": "your_username",
    "password": "your_password"
  }'

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 86400
}

Use JWT Token

curl -H "Authorization: Bearer JWT_TOKEN"   https://api.railwise.cn/v1/projects

Refresh Token

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

3. Permission Control

3.1 Permission Levels

Permission Level	Scope	Description
Read	GET requests	View data, cannot modify
Write	POST/PUT/PATCH	Create and modify data
Delete	DELETE	Delete data
Admin	All operations	System management

3.2 Resource Permissions

Resource	Read	Write	Delete	Admin
Projects	●	●	●	●
Data	●	●	-	●
Reports	●	●	-	●
Users	-	-	-	●
Settings	-	-	-	●

3.3 Project-level Permissions

Role	Project View	Data View	Data Edit	Report Generate	Project Manage
Viewer	●	●	-	-	-
Editor	●	●	●	-	-
Reporter	●	●	●	●	-
Manager	●	●	●	●	●

4. Token Management

4.1 Token Lifecycle

Token Type	Validity Period	Refresh Method
API Key	Permanent	Manual regeneration
Access Token (OAuth)	1 hour	Refresh token
JWT Token	24 hours	Refresh token
Refresh Token	30 days	Re-login

4.2 Token Security

1. Secure Storage: Store tokens in environment variables or secure key management systems, never hardcode in code
2. Regular Rotation: Regularly rotate API keys and refresh tokens
3. Scope Limitation: Grant minimum necessary permissions to tokens
4. Monitoring Audit: Monitor API call logs, detect abnormal access

4.3 Token Revocation

If a token is leaked or no longer needed, revoke it immediately:

# Revoke API Key
curl -X DELETE https://api.railwise.cn/v1/api-keys/KEY_ID   -H "Authorization: Bearer ADMIN_TOKEN"

# Revoke Access Token
curl -X POST https://api.railwise.cn/v1/oauth/revoke   -H "Content-Type: application/x-www-form-urlencoded"   -d "token=ACCESS_TOKEN"

5. Security Best Practices

5.1 HTTPS Only

All API calls must use HTTPS. HTTP requests will be rejected.

5.2 Request Signing

For high-security scenarios, request signing can be used:

# Generate signature
SIGNATURE=$(echo -n "GET|/v1/projects|timestamp=1234567890" | openssl dgst -sha256 -hmac "SECRET_KEY")

# Request with signature
curl -H "X-API-Key: API_KEY"   -H "X-Timestamp: 1234567890"   -H "X-Signature: $SIGNATURE"   https://api.railwise.cn/v1/projects

5.3 IP Whitelist

Restrict API access to specific IP addresses:

1. Log in to Console
2. Go to Settings > Security
3. Add IP whitelist

5.4 Rate Limiting

Plan	Rate Limit	Burst Limit
Free	100 requests/minute	150
Professional	1000 requests/minute	1500
Enterprise	10000 requests/minute	15000

6. Error Handling

6.1 Authentication Errors

Error Code	Description	Solution
401	Unauthorized	Check token validity
403	Forbidden	Check permission scope
429	Too Many Requests	Reduce request frequency
498	Token Expired	Refresh or re-obtain token

7. Related Documents

• REST API Reference
• Data Ingestion Specification
• Webhook Integration Guide
• Error Codes

---

RailWise · Smart Monitoring — Engineering Surveying and Safety Monitoring Digital Solutions