sa-token

Original：🇨🇳 Chinese

Translated

Core skill for Sa-Token, a lightweight Java authentication and authorization framework. It covers login authentication, permission/role authentication, annotation-based authorization, route-interceptor authorization, Session management, forced logout, Token expiration strategies, framework configuration, Token styles and submission prefixes, frontend-backend separation, remember-me mode, mutually exclusive login on the same device, and handling NotLoginException scene values. StpUtil is the core facade utility class and provides a complete suite of authentication APIs, including login/checkLogin/logout/isLogin/getLoginId/getTokenValue. Use this skill when users need to integrate permission authentication into Java Web projects, use StpUtil for login and permission validation, configure route interceptors, or implement annotation-based authorization. It does not cover advanced features such as secondary authentication, account banning, multi-account support, SSO, OAuth2, microservices, API security, JWT, or Redis; use the corresponding specialized skills for those.

4installs

Sourcefull-stack-skills/java-skills

Added on2026-10-18

NPX Install

npx skill4agent add full-stack-skills/java-skills sa-token

SKILL.md Content (Chinese)

View Translation Comparison →

Sa-Token Core Permission Authentication Framework

Based on Sa-Token v1.45.0 | Official documentation: https://sa-token.cc | GitHub: https://github.com/dromara/sa-token

Sa-Token is a lightweight Java permission authentication framework. Its core package is dependency-free and provides a complete access-control system.

StpUtil

is its core facade utility class.

Capability Boundaries

✅ Best-Fit Capabilities

Login Authentication —
```
StpUtil.login()
```
supports session login, remember-me mode, specified device types, and extended login parameters
Session Validation — a complete suite of query APIs, including
```
StpUtil.isLogin()
```
/
```
checkLogin()
```
/
```
getLoginId()
```
Token Management — retrieve Token values, names, and information; look up accounts by Token; dual Token expiration strategies (timeout + active-timeout)
Permission/Role Authentication — implement StpInterface to define a permission loader, the checkPermission/checkRole API family, and the permission wildcard
```
*
```

Annotation-Based Authorization —

@SaCheckLogin

,

@SaCheckPermission

,

@SaCheckRole

,

@SaIgnore

,

@SaCheckOr

Route-Interceptor Authorization — SaInterceptor + SaRouter matching chains, stop/back/free exit mechanisms, and multi-condition matching
Session Management — three models: Account-Session / Token-Session / Custom-Session
Forced Logout — three operations: forced session termination, kickout, and replacement of an existing online session
Framework Configuration — all application.yml options and code-based configuration methods
Frontend-Backend Separation — Cookie mode vs. Header mode, with adaptation for mini programs and apps that do not support Cookies
Token Customization — six built-in styles, custom generation strategies, and Bearer submission prefixes
Mutually Exclusive Login on the Same Device — only one online session is allowed per device type

❌ Out of Scope (Alternatives)

Secondary authentication/account banning/impersonation/multi-account support → sa-token-advanced
SSO single sign-on → sa-token-sso
OAuth2.0 server → sa-token-oauth2
Microservices Same-Token/gateway authorization → sa-token-micro
API signing/API Key/temporary Token → sa-token-api-security
JWT integration/Redis persistence/template engine → sa-token-integration

Applicable Scenarios

Activate this skill when users need the following:

Permission authentication integration for a new project — add Sa-Token to a Spring Boot project, configure StpInterface, and implement login and permission validation
Add authentication to an existing project — add login validation, permission validation, and role validation to existing APIs
Configure a route interceptor — centrally intercept all requests and apply different authorization rules by module
Use annotation-based authorization — use annotations such as
```
@SaCheckLogin
```
and
```
@SaCheckPermission
```
Frontend-backend separation adaptation — Token transmission and validation in environments without Cookie support
Debugging and troubleshooting — diagnose different NotLoginException scene values and Token expiration issues

Workflow

Step 1. Add the dependency — add the

sa-token-spring-boot-starter

dependency, selecting the appropriate version for the Spring Boot version Step 2. Configure the framework — configure the Token name, expiration, style, and other options in application.yml Step 3. Implement StpInterface — customize the permission loader to return permission codes and role sets Step 4. Login authentication — call

StpUtil.login(id)

to complete session login Step 5. Permission validation — use StpUtil methods or annotations for permission and role validation Step 6. Route interception — implement global route authorization with SaInterceptor + SaRouter Step 7. Integration testing — verify the complete flow of login/logout, permission validation, and annotation-based authorization

StpUtil Core API Quick Reference

java

// === 登录认证 ===
StpUtil.login(Object loginId);                          // 会话登录
StpUtil.login(10001, "PC");                             // 指定设备类型
StpUtil.login(10001, true);                             // 指定记住我
StpUtil.login(10001, new SaLoginParameter()...);        // 完整参数模式
StpUtil.logout();                                       // 当前会话注销
StpUtil.logout(10001);                                  // 指定账号注销
	StpUtil.logoutByTokenValue(token);                      // 指定Token注销
	StpUtil.logoutByLoginId(10001, "PC");                   // 指定账号+设备注销
	StpUtil.kickout(10001);                                 // 踢人下线
	StpUtil.kickoutByTokenValue(token);                     // 根据Token值踢人
StpUtil.isLogin();                                      // 是否登录(true/false)
StpUtil.checkLogin();                                   // 校验登录(未登录抛NotLoginException)

	// === 会话/Token查询 ===
	StpUtil.getLoginId();                                   // 当前账号id
	StpUtil.getLoginIdAsString()/AsInt()/AsLong();          // 类型化获取
	StpUtil.getLoginIdDefaultNull();                        // 未登录返回null
	StpUtil.getLoginIdByToken(token);                       // 根据token查账号
	StpUtil.getTokenValue();                                // 当前token值
	StpUtil.getTokenValueByLoginId(10001);                  // 获取指定账号的token值
	StpUtil.getTokenListByLoginId(10001);                   // 获取指定账号所有token列表
	StpUtil.getTokenName();                                 // token名称(satoken)
	StpUtil.getTokenTimeout();                              // 剩余有效期(秒)
	StpUtil.getTokenInfo();                                 // 完整TokenInfo
	StpUtil.setTokenValue("xxx-xxx");                       // 手动设置当前会话token值
	StpUtil.renewRefresh();                                // 自动续签token有效期
	StpUtil.getTerminalListByLoginId(10001);                // 获取指定账号所有终端列表

	// === 权限/角色校验 ===
	StpUtil.getPermissionList();                            // 权限码集合
	StpUtil.hasPermission("user.add");                     // boolean
	StpUtil.checkPermission("user.add");                   // 失败抛NotPermissionException
	StpUtil.checkPermissionAnd("add","del","get");          // 全部拥有
	StpUtil.checkPermissionOr("add","del","get");          // 至少一个
	StpUtil.hasRole("admin");                               // boolean
	StpUtil.checkRole("admin");                             // 失败抛NotRoleException
	
	// === Session会话 ===
	StpUtil.getSession();                                   // 当前账号Account-Session
	StpUtil.getSessionByLoginId(10001);                     // 指定账号的Session
	StpUtil.getTokenSession();                              // 当前Token-Session
	StpUtil.getTokenSessionByTokenValue("xxx-xxx");        // 按token值获取Token-Session
	SaSessionCustomUtil.getSessionById("goods-10001");     // Custom-Session

Reference Documentation

Topic	File	Source
Complete Login Authentication Guide	references/login-auth.md	GitHub
Permission/Role Authentication	references/jur-auth.md	GitHub
Annotation-Based Authorization	references/at-check.md	GitHub
Route-Interceptor Authorization	references/route-check.md	GitHub
Session Management	references/session.md	GitHub
Framework Configuration	references/config.md	GitHub
Forced Logout	references/kickout.md	GitHub
Token Expiration	references/token-timeout.md	GitHub
NotLoginException	references/not-login-scene.md	GitHub
Frontend-Backend Separation & Remember Me	references/not-cookie.md	GitHub, remember-me
Token Style & Prefix	references/token-style.md	GitHub, token-prefix
Login Parameter Details	references/login-parameter.md	GitHub
Mutually Exclusive Login on the Same Device	references/mutex-login.md	GitHub
Quick Start	examples/quickstart.md	GitHub

Gotchas

StpInterface is not executed at startup — queries are triggered only when an authorization method is called
Annotation-based authorization is disabled by default —
```
SaInterceptor
```
must be registered manually
SaSession ≠ HttpSession — the two are completely unrelated and should not be confused
Frontend authorization is only supplementary — it cannot replace backend validation
@SaIgnore
only applies to SaInterceptor and AOP — custom interceptors are unaffected
@SaCheckPermission
uses AND mode by default — OR mode requires
```
mode = SaMode.OR
```
The logout scope of
StpUtil.logout()
can be configured through
logout-range
— by default, only the current Token is logged out
Cookie mode injects a Cookie by default — it can be disabled with
```
is-read-cookie: false
```

Data Privacy

This skill does not collect, store, or transmit any user data.