Based on sa-token-doc/plugin/api-sign.md(591 lines) + api-key.md(283 lines) + temp-token.md(120 lines).
Capability Boundaries
✅ Strong Suits
- API Parameter Signing — Anti-tampering and anti-replay for cross-system interfaces (timestamp+nonce+sign four-step evolution)
- Multi-Application Signing Mode — Multiple sets of secret-key, different digest algorithms (md5/sha256/sha512)
- API Key Management — Partial authorization for third-party developers, Scope permission control, revocable
- API Key Multi-Account System — Independent API Key templates for different account systems
- API Key Database Mode — Implement the DataLoader interface to persist to the database
- Temporary Token — Short-lived link invitation, non-session-based authorization
- Temporary Token Prefix Trimming — Distinguish by adding prefixes per business line
- Temporary Token Reverse Lookup — Reverse lookup all tokens based on value
⚠️ Requirements
- API signing requires both communicating parties to negotiate a secret-key
- API Keys are stored in the cache by default (lost on restart); persistence requires implementing DataLoader
- Temporary Tokens are embedded in the core package, no additional dependencies required
❌ Out of Scope
- Basic login/permission authentication → sa-token
- JWT integration/Redis → sa-token-integration
- Microservice Same-Token → sa-token-micro
When to Use Which Feature
| Scenario | Recommended Solution | Reason |
|---|---|---|
| System A calls System B's API to prevent parameter tampering | API Signing | Lightweight, no additional storage required |
| Provide API access credentials to third-party developers | API Key | Revocable, controllable Scope permissions |
| Generate a short-term invitation link | Temporary Token | Stateless, specifies expiration time |
| Need both anti-tampering + identity authentication | API Signing + API Key | Both can be used simultaneously |
Workflow
API Signing Workflow
Step 1. Introduce the sa-token-sign dependency
Step 2. Configure secret-key and the digest algorithm
Step 3. The requesting side uses SaSignUtil.addSignParamsAndJoin() to construct the signed parameters
Step 4. The receiving side uses SaSignUtil.checkRequest() or @SaCheckSign to verify
API Key Workflow
Step 1. Introduce the sa-token-apikey dependency
Step 2. Call SaApiKeyUtil.createApiKeyModel() to create an API Key
Step 3. The client submits the apikey via request parameters or header
Step 4. The server uses the @SaCheckApiKey annotation to verify
Temporary Token Workflow
Step 1. Call SaTempUtil.createToken() to create a temporary Token
Step 2. Pass the Token to the user (URL/message, etc.)
Step 3. The user calls SaTempUtil.parseToken() to parse
Reference Documentation
| Topic | File | Source |
|---|---|---|
| API Parameter Signing (Anti-Tampering Anti-Replay) | references/api-sign.md | GitHub |
| API Key (Partial Authorization Management) | references/api-key.md | GitHub |
| Temporary Token (Short-Lived Link) | references/temp-token.md | GitHub |
FAQ
Q: What is the difference between API signing and Same-Token? A: The API signature is used for parameter anti-tampering and anti-replay (data integrity), while Same-Token is used for inter-service identity authentication (authentication). They can be used at the same time.
Q: What is the difference between API Key and session Token? A: API Key is static, revocable, and Scope-restricted. Session Token is dynamic, automatically obtained after login, and has full account permissions. They serve different scenarios and cannot replace each other.
Q: How do I set the validity period of a temporary Token?
A: Specify it via the second parameter at creation time (in seconds), e.g. SaTempUtil.createToken("10014", 200) means 200 seconds.
Q: How do I persist an API Key to the database?
A: Implement the SaApiKeyDataLoader interface. The framework checks the cache first, and when the cache does not exist, calls DataLoader to load from the database.
Q: Can a temporary Token use JWT mode?
A: Yes. Introduce the sa-token-temp-jwt dependency and configure jwt-secret-key. The upper-layer API remains unchanged and the underlying implementation uses the JWT kernel.
Gotchas
- Do not hardcode the secret-key in the API signature in the code — it should be configured in a configuration center or environment variable
- The API Key is saved in the cache by default — it is lost after restart; if you need database mode, implement DataLoader
- When a temporary Token is created, no index is recorded (third parameter=false) — by default, the token corresponding to a value cannot be looked up in reverse
- When trimming the API prefix, specifying the wrong prefix returns null — it does not throw an exception
- After the secret-key of the API signature is leaked, it must be replaced immediately — after replacement, all requests using the old key will fail
- Multiple API Keys can be granted different Scopes — achieve minimized authorization
- Temporary Tokens can be used for authorization in non-login scenarios — for example, email verification links and invitation registration links
- The default timestamp gap for the API signature is 15 minutes — it can be adjusted according to network latency
Data Privacy
This skill does not collect, store, or transmit any user data. All code examples are for local development reference only.