Skip to main content

​
Authentication

Profy uses a dual authentication system: SMS + JWT for end users and API Keys for programmatic access. All sessions are backed by Redis with single-device enforcement.

​
Overview

​
SMS Login Flow

Users authenticate by verifying ownership of a phone number via SMS verification code.

​
SMS Providers

ProviderUse CaseConfiguration
Aliyun SMSPrimary providerALIYUN_SMS_ACCESS_KEY_ID, ALIYUN_SMS_ACCESS_KEY_SECRET
VolcengineAlternative providerVOLCENGINE_SMS_* env vars
An optional Aliyun CAPTCHA challenge can be required before sending SMS to prevent abuse.

​
JWT Token System

Tokens are signed using the jose library with HS256 algorithm.

​
Token Structure

interface JWTPayload {
  userId: string;
  phone: string;
  iat: number;
  exp: number;   // 7 days from issuance
}

​
Redis Session Keys

Each login creates two Redis entries for bidirectional lookup:
Key PatternValueTTLPurpose
auth:token:{token}User JSON payload24h (auto-refreshed)Token → user lookup
auth:user-token:{userId}Token string24hUser → token lookup (single-device)

​
Single-Device Enforcement

When a user logs in from a new device, the previous session is invalidated:
  1. Look up existing token via auth:user-token:{userId}
  2. Delete old auth:token:{oldToken} entry
  3. Store new token in both keys
This ensures only one active session per user at any time.

​
Auth Middleware

The auth filter runs on every request and applies route-level access control.

​
Whitelisted Routes (No Auth Required)

RouteReason
/api/auth/loginLogin endpoint
/api/auth/sms/sendCodeSMS dispatch
/api/healthHealth check
/api/market/*Public marketplace browsing
/api/payment/notify/*Payment provider callbacks

​
Middleware Flow

The middleware extracts tokens from either:
  • Authorization: Bearer <token> header
  • Cookie: token=<token> cookie

​
API Key System

API Keys provide programmatic access to the /openapi/* endpoints, used primarily by the Profy agent engine for credit consumption.

​
Key Format

All API keys use the sk_ prefix followed by a cryptographically random string.

​
API Key Endpoints

MethodEndpointDescription
POST/api/user/apiKey/createGenerate a new API key
POST/api/user/apiKey/listList user’s API keys
POST/api/user/apiKey/deleteRevoke an API key

​
Key Storage

API keys are stored in Redis under openapi:key:{key} with the associated user payload. Validation is a simple Redis lookup — no JWT verification needed.

​
OpenAPI Endpoints (API Key Auth)

MethodEndpointDescription
POST/openapi/credit/consumeConsume credits (used by Profy)
POST/openapi/credit/preCheckPre-validate consumption
GET/openapi/credit/balanceQuery credit balance

​
Security Considerations

ConcernMitigation
SMS abuseRate limiting (60s cooldown per phone), optional CAPTCHA
Token leakage24h Redis TTL, single-device enforcement
Replay attacksJWT expiry (7d), Redis-backed session invalidation
API Key exposureRevocable keys, sk_ prefix for easy scanning
Internal endpoints/internal/* routes restricted to private network via Nginx

​
Token Refresh

The platform provides a token refresh endpoint at GET /api/token/refresh that issues a new JWT before the current one expires, maintaining seamless session continuity.

Architecture

See how auth fits into the request lifecycle

Agent Platform

API Keys power the Profy credit consumption bridge