feishu-user-auth

Original：🇨🇳 Chinese

Translated

14 scripts

Use this skill when users mention scenarios such as "Feishu authorization", "OAuth", "Device Flow", "open_id", "repeated authorization pop-ups", "token reuse", "supplement authorization scopes", or "where Feishu tokens are stored"—scenarios that require reusing existing local user tokens, only supplementing missing scopes, or troubleshooting the actual storage location of tokens.

2installs

Sourceshuliuzhenhua-sys/shuliu-skills

Added on2026-03-28

NPX Install

npx skill4agent add shuliuzhenhua-sys/shuliu-skills feishu-user-auth

SKILL.md Content (Chinese)

View Translation Comparison →

Feishu User Auth

This skill only handles two things:

Initiate Feishu user authorization
Reuse existing tokens as much as possible to avoid repeated authorization pop-ups

When to Use

Use this skill directly when users have the following needs:

Implement user authorization for Feishu applications
Troubleshoot why authorization pop-ups keep appearing repeatedly
Check if a user has already authorized locally
Want to add new scopes without losing old authorizations
Want to delete a user's local token and re-authorize

Storage Location

By default, this skill stores tokens in the user directory:

```
~/.feishu-auth/tokens/<appId>.json
```

If you explicitly configure

storeDir

in

config.json

, the path will be changed to:

```
<storeDir>/tokens/<appId>.json
```

storeDir

supports absolute paths or user directory paths like

~/.feishu-auth

.

For older versions where tokens are stored in the legacy directory, the script will attempt to migrate from these two locations:

```
<legacyStoreDir>/tokens/<appId>.json
```
```
<legacyStoreDir>/<appId>__<openId>.json
```

The script will use this old directory as the default migration source and automatically attempt migration when the new directory is empty.

Pre-configuration

First, find the installed skill directory, then maintain the

config.json

file within it.

Common installation locations:

Project-local installation:

./.agents/skills/feishu-user-auth/config.json

Global installation (

npx skills add ... -g

):

~/.agents/skills/feishu-user-auth/config.json

If you don't want to modify the skill directory, you can prepare your own configuration file and pass it in via

--config

later.

Format as follows:

json

{
  "appId": "cli_xxx",
  "appSecret": "replace-with-app-secret",
  "brand": "feishu"
}

Notes:

```
appId
```
and
```
appSecret
```
are required
```
brand
```
is optional, default is
```
feishu
```
```
storeDir
```
is optional; if not specified, the default is
```
~/.feishu-auth
```
If
```
storeDir
```
is explicitly filled in, it can be an absolute path or
```
~/.feishu-auth
```
```
legacyStoreDir
```
is optional, default points to the skill's own
```
state/
```
directory

This set of scripts no longer depends on environment variables like

FEISHU_APP_ID

,

FEISHU_APP_SECRET

,

FEISHU_BRAND

, and

FEISHU_AUTH_*

in the system.

Execution Methods

After installation,

feishu-auth

is not automatically added to the PATH by default.

The most reliable way to call it is to directly execute the bin file in the installation directory:

bash

./.agents/skills/feishu-user-auth/bin/feishu-auth.js auth

If installed globally, you can execute it from any directory:

bash

~/.agents/skills/feishu-user-auth/bin/feishu-auth.js auth

If you want to use the

feishu-auth

command name directly, you can create a link yourself:

bash

mkdir -p ~/.local/bin
ln -sf ~/.agents/skills/feishu-user-auth/bin/feishu-auth.js ~/.local/bin/feishu-auth

Then ensure

~/.local/bin

is in your PATH, and you can execute directly:

bash

feishu-auth auth

Available commands:

bash

<skill-dir>/bin/feishu-auth.js auth [--batch-size 60] [--open-id ou_xxx]
<skill-dir>/bin/feishu-auth.js user-auth [--batch-size 60] [--open-id ou_xxx]
<skill-dir>/bin/feishu-auth.js auth --scope "scope1 scope2"
<skill-dir>/bin/feishu-auth.js refresh-token [--open-id ou_xxx]
<skill-dir>/bin/feishu-auth.js refresh-token [--open-id ou_xxx] --force
<skill-dir>/bin/feishu-auth.js show-token
<skill-dir>/bin/feishu-auth.js show-token --open-id ou_xxx
<skill-dir>/bin/feishu-auth.js remove-token --open-id ou_xxx
<skill-dir>/bin/feishu-auth.js system-token
<skill-dir>/bin/feishu-auth.js system-auth
<skill-dir>/bin/feishu-auth.js --config /path/to/config.json auth
<skill-dir>/bin/feishu-auth.js --help

If you are developing locally in a repository, you can execute the source code entry in the repository root directory:

bash

node skills/feishu-user-auth/scripts/run-auth.js auth

Working Rules

Follow this sequence:

Prioritize reusing saved tokens
If
```
--open-id
```
is not specified, automatically select the most suitable user record to reuse
If the application's scopes are more than the locally authorized scopes, only supplement the missing parts
After batch authorization, save the union of scopes and do not overwrite old batches

Troubleshooting Key Points

If users say "It still pops up even though I've authorized before", check these items first:

Whether the script of this skill is used, instead of other scripts
Whether the
```
appId
```
in
```
config.json
```
corresponds to the same app as the old token
Whether there is indeed a record for the app in the current
```
storeDir/tokens/
```
Whether the scopes required this time exceed the historically authorized scope
Whether the token has
```
expired
```
or is in
```
needs_refresh
```
status

Output Requirements

Inform users of these key pieces of information:

Which
```
open_id
```
was reused
Whether re-authorization is actually needed this time
If needed, which scopes are missing
The final location of the token in the
```
storeDir/tokens/<appId>.json
```
file

feishu-user-auth

NPX Install

Tags

SKILL.md Content (Chinese)

Feishu User Auth

When to Use

Storage Location

Pre-configuration

Execution Methods

Working Rules

Troubleshooting Key Points

Output Requirements