feishu-user-auth

Feishu User Auth

This skill is only responsible for two things:

Initiate Feishu user authorization
Reuse existing tokens as much as possible to avoid repeatedly showing the authorization page

When to use

Use it directly when the user has these needs:

Set up user authorization for a Feishu app
Troubleshoot why the authorization window keeps popping up repeatedly
Want to know whether a certain user has already been authorized locally
Want to add a batch of new scopes without losing the old authorization
Want to delete a certain user's local token and reauthorize

Storage location

By default, this skill stores the token under the user directory:

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

If you explicitly configure config.json in storeDir, it will instead become:

<storeDir>/tokens/<appId>.json

storeDir supports absolute paths, and also supports writing it as a user directory path like ~/.feishu-auth .

In older versions, if the token is still placed under the legacy directory, the script will try to migrate from these two locations:

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

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

Prerequisite configuration

First locate the installed skill directory, then maintain the config.json。

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 do not want to modify the skill directory, you can also prepare your own configuration file and pass it in later via --config .

The format is as follows:

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

Notes:

appId、appSecret Required
brand Optional, default feishu
storeDir Optional; if not filled in, the default is ~/.feishu-auth
If you explicitly fill in storeDir, you can write an absolute path or a ~/.feishu-auth
legacyStoreDir Optional, defaults to the skill's own state/

This set of scripts no longer depends on the system's FEISHU_APP_ID、FEISHU_APP_SECRET、FEISHU_BRAND、FEISHU_AUTH_* environment variable.

How to execute

After installation, by default feishu-auth will not be automatically added to PATH.

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

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

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

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

If you want to use the feishu-auth command name directly, you can add a link yourself:

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

Then make sure ~/.local/bin is in PATH, and you can execute it directly:

feishu-auth auth

Available commands:

<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 the repository, only then is it appropriate to execute the source entry point from the repository root:

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

Working rules

Do it in this order:

Prioritize reusing saved tokens
If --open-idis not specified, automatically select the most suitable user record for reuse
If the app scopes exceed the locally authorized scopes, only supplement the missing parts
After authorizing in batches, save the scopes as a union; do not overwrite old batches

Troubleshooting focus

If the user says "I clearly authorized it but it still pops up", first check these items:

Whether this skill's script was used, rather than directly running some other script
config.json in appId whether the same app corresponds to the old token
Currently storeDir/tokens/ does indeed have a record of this app
Whether the scopes requested this time exceed the previously authorized scope
Whether the token has already expired, or only needs_refresh

Output requirements

Tell the user these key pieces of information:

Which open_id
Whether reauthorization is really needed this time
If needed, because which scopes are missing
Which storeDir/tokens/<appId>.json file the token ultimately ends up in